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Preface 


Intended Audience 


This manual is intended for all programmers who 
routines. 

call VMS-supplied system 

Document Structure 



This manual contains two chapters and an appendix. 

• Chapter 1 describes the format used to document system routines. 

• Chapter 2 describes the VAX Procedure Calling and Condition Handling 
Standard. This standard explains programming mechanisms that are used 
with the VAX hardware procedure-calling mechanism. 

• Appendix A describes VMS data types, the VMS Usage entry, and the 
VAX language implementation tables. 


Associated Documents 

The following four manuals document the VMS-supplied system routines: 

• VMS System Services Reference Manual 

• VMS Run-Time Library Routines Volume 

• VMS Record Management Services Manual 

• VMS Utility Routines Manual 

The VAX Architecture Reference Manual and the VAX Architecture Handbook 
also contain information about the VAX architecture and its procedure-calling 
mechanisms. 







Preface 


Conventions 


Convention 

Meaning 

[reU 

In examples, a key name (usually abbreviated) 
shown within a box indicates that you press 
a key on the keyboard; in text, a key name is 
not enclosed in a box. In this example, the key 
is the RETURN key. (Note that the RETURN 
key is not usually shown in syntax statements 
or in all examples; however, assume that you 
must press the RETURN key after entering a 
command or responding to a prompt.) 

CTRL/C 

A key combination, shown in uppercase with a 
slash separating two key names, indicates that 
you hold down the first key while you press the 
second key. For example, the key combination 
CTRL/C indicates that you hold down the key 
labeled CTRL while you press the key labeled C. 
In examples, a key combination is enclosed in a 
box. 

$ SHOW TIME 
05-JUN-1988 11:55:22 

In examples, system output (what the system 
displays) is shown In black. User Input (what 
you enter) is shown in red. 

$ TYPE MYFILE.DAT 

In examples, a vertical series of periods, or 
ellipsis, means either that not all the data that 
the system would display in response to a 
command is shown or that not all the data you 
would enter is shown. 

input-file, . . . 

In examples, a horizontal ellipsis indicates 
that additional parameters, values, or other 
Information can be entered, that preceding 
items can be repeated one or more times, or 
that optional arguments in a statement have 
been omitted. 

[logical-name] 

Brackets indicate that the enclosed item is 
optional. (Brackets are not, however, optional 
in the syntax of a directory name In a file 
specification or In the syntax of a substring 
specification in an assignment statement.) 

quotation marks 
apostrophes 

The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe is used to refer to a single quotation 
mark ('). 


xii 
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New and Changed Features 


This version of the Introduction to VMS System Routines contains no new 
technical information. 
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Documentation Format for System Routines 


Overview 

Nli 


Each system routine is documented using a structured format. This chapter 
discusses the main categories in this format, the information presented under 
each, and the format used to present the information. 

This chapter explains where to find information on routines and how to read 
that information correctly. Subsequent chapters cover the VAX Procedure 
Calling and Condition Handling Standard and VMS Data Types. 

Note: The documentation format described in this chapter is generic; portions 
of it are used or not used, as appropriate, in the four VMS manuals that 
document system routines. 

VMS System Services Reference Manual 
VMS Run-Time Library Routines Volume 
VMS Utility Routines Manual 
VMS Record Management Services Manual 

Some main categories in the routine format contain information requiring 
no explanation beyond that given in Table 1-1. However, additional 
information, presented in this manual, is required for the following categories: 

• Format 

• Returns 

• Arguments 

• Condition Values Returned 
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Table 1-1 Main Heading in the Documentation Format for System 
Routines 


Main Heading 

Description 

Routine Name 

Always present. The routine entry-point name appears 
at the top of the first page. It is usually, though not 
always, followed by the English text name of the 
routine. 

Routine Overview 

Always present. The routine overview appears directly 
below the routine name; the overview explains, usually 
in one or two sentences, what the routine does. 

Format 

Always present. The format heading follows the 
routine overview. The format gives the routine entry- 
point name and the routine argument list. 

Returns 

Always present. The returns heading follows the 
routine format. It explains what information is returned 
by the routine. 

Arguments 

Always present. The arguments heading follows 
the returns heading. Detailed information about each 
argument is provided under the arguments heading. 

If a routine takes no arguments. It is indicated by the 
word "None." 

Description 

Optional. The description heading follows the 
arguments heading. The description section contains 
information about specific actions taken by the 
routine: interaction between routine arguments. If 
any; operation of the routine within the context of 

VMS; user privileges needed to call the routine. If any; 
system resources used by the routine; and user quotas 
that may affect the operation of the routine. 

Note that any restrictions on the use of the routine 
are always discussed first In the description section; 
for example, any required user privileges or necessary 
system resources are explained first. 

For some simple routines, a description section is not 
necessary because the routine overview provides the 
needed information. 

Condition Values 
Returned 

Always present. The condition values returned section 
follows the description section. It lists the condition 
values (typically status or completion codes) that are 
returned by the routine. 
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Table 1-1 (Cent.) Main Heading in the Documentation Format for 
System Routines 


Main Heading 

Description 


Example 

Optional. The examples heading appears following 
the condition values returned heading. The example 
section contains one or more programming examples 
that illustrate how to use the routine, and is followed 
by an explanation. 

All examples have been tested and should run when 
compiled (or assembled) and linked. Incomplete 
examples and code fragments do not appear under 
the examples heading. Throughout the manuals that 
document system routines, examples are provided in 
as manv different programming languages as possible. 


1.2 Format Heading 

The following three types of information can be present in the format 
heading: 

• Procedure call format 

• JSB Oump to Subroutine) format 

• Explanatory text 

All system routines have a procedure call format, but not all system routines 
have JSB formats; most do not. If a routine has a JSB format, it always 
appears after the routine's procedure call format. 

Procedure Call Format 

The procedure call format ensures that a routine call conforms to the 
procedure call mechanism described in the VAX Procedure Calling and 
Condition Handling Standard in Chapter 2; for example, an entry mask is 
created, registers are saved, and so on. 

Procedure call formats can appear in many forms. The following four 
examples illustrate the meaning of syntactical elements, such as brackets 
and commas. General rules of syntax governing how to use procedure call 
formats are shown in Table 1-2. 

Example 1 

This example illustrates the standard representation of optional arguments 
and best describes the use of commas as delimiters. Arguments enclosed 
within square brackets are optional, but if an optional argument other than 
a trailing optional argument is omitted, you must include a comma as a 
delimiter for the omitted argument. 

ENTRY-POINT-NAME argl [.[arg2 [,arg3]] 

Typically, VMS RMS system routines use this format where, at most, three 
arguments appear in the argument list. 
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Example 2 

When the argument list contains three or more optional arguments, the syntax 
does not provide enough information. If you omit the optional arguments 
arg3 and arg4 and specify the trailing argument argS, you must use commas 
to delimit the positions of the omitted arguments. 

ENTRY-POINT-NAME argl ,arg2 ,[arg3] .nullarg [,arg4] [,arg5] 

Typically, VMS system services, utility routines, and VAX Run-Time Library 
routines contain call formats with more than three arguments. 

Example 3 

In the following call format example, the trailing four arguments are optional 
as a group; that is, either you specify arg2, arg3, arg4, and argS, or none of 
them. Therefore, if you do not specify the optional arguments, you need not 
use commas to delimit unoccupied positions. 

However, if you specify a required argument or a separate optional argument 
after argS, you must use commas when arg2, arg3, arg4, and argS are omitted. 

ENTRY-POINT-NAME argl [,arg2 ,arg3 .arg4 .arg5] 

Example 4 

In the following example, you may specify arg2 and omit arg3. However, 
whenever you specify arg3, you must specify arg2. 

ENTRY-POINT-NAME argl [.arg2 [.arg3]] 

JSB Call Format 

The JSB call format activates the routine code directly, without the overhead 
of constructing the entry mask or saving registers. You can use the JSB call 
format only with the VAX MACRO and VAX BLISS languages. 

Explanatory Text 

Explanatory text may follow the procedure call format or the JSB call format, 
or both. This text is present only when needed to clarify the format. For 
example, in the call format, you indicate that arguments are optional by 
enclosing them in brackets ([]). However, brackets alone cannot convey 
all the important information that may apply to optional arguments. For 
example, in some routines that have many optional arguments, if you select 
one optional argument, you must also select another optional argument. In 
such cases, text following the format clarifies this. 

Table 1—2 General Rules of Syntax 
Element Syntax Rule 


Entry point names Entry point names are always shown in uppercase 

characters. 

Argument names Argument names are always shown in lowercase 

characters. 
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Table 1-2 (Cent.) 

General Rules of Syntax 

Element 

Syntax Rule 

Spaces 

One or more spaces are used between the entry 
point name and the first argument, and between 
each argument. 

Braces 

Braces surround two or more arguments. You 
must choose one of the arguments. 

Brackets ([]) 

Brackets surround optional arguments. Note that 
commas too can be optional (see the comma 
element). 

Commas 

Between arguments, the comma always follows 
the space. If the argument is optional, the comma 
may appear inside the brackets or outside the 
brackets, depending on the position of the 
argument in the list and on whether surrounding 
arguments are optional or required. 

Null arguments 

A null argument is a place-holding argument. It Is 
used for either of the following reasons: { 1 ) to 
hold a place in the argument list for an argument 
that has not yet been implemented by DIGITAL but 
may be in the future; or ( 2 ) to mark the position 
of an argument that was used in earlier versions 
of the routine but is not used In the latest version 
(upward compatibility is thereby ensured because 
arguments that follow the null argument in the 
argument list keep their original positions). A null 
argument is always given the name nullarg. 


In the argument list constructed on the stack when 
a procedure is called, both null arguments and 
omitted optional arguments are represented by 
longword argument list entries containing the value 
0 . The programming language syntax required to 
produce argument list entries containing 0 differs 
from language to language. See your language 
user's guide for language-specific syntax. 


Returns Heading 

The returns heading contains a description of any information returned by the 
routine to the caller. A routine can return information to the caller in various 
ways. The following subsections discuss each possibility and then describe 
how this returned information is presented. 
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1.3.1 Condition Vatues Returned in RO 

Most routines return a condition value in register RO. This condition value 
contains various kinds of information, but most importantly for the caller, it 
describes (in bits <3:0> ) the completion status of the operation. You test 
the condition value to determine if the routine completed successfully. 

If you program in high-level languages, the fact that status information is 
returned by ineans of a condition value and that it is returned in a VAX 
register is of little importance because you receive this status information in 
the return (or status) variable. The run-time environment established for the 
high-level language program allows the status information in RO to be moved 
automatically to the user's return variable. 

Nevertheless, for routines that return a condition value in RO, the returns 
heading in the documentation contains the following information: 

VMS Usage: longword_unsigned 

■type: longword (unsigned) 

access: write only 

mechanism: by value 

The VMS Usage entry specifies the VMS data type of the information returned. 
Because the data type of a condition value in the VMS operating system 
environment is an unsigned longword, the VMS Usage entry is 

longword—unsigned. 

The type entry specifies the data type of the information returned. Because 
the data type of a condition value is an unsigned longword, the type heading 
is longword (unsigned). 

The access entry specifies the way in which the called routine accesses the 
object. Because the called routine is returning the condition value, it is writing 
into this longword, so the access heading is write only. 

The mechanism heading specifies the passing mechanism used by the called 
routine in returning the condition value. Because the called routine is writing 
the condition value directly into RO, the mechanism heading is by value. (If 
the called routine had written the address of the condition value into RO, the 
passing mechanism would have been by reference.) 

Note that if a routine returns a condition value in RO, another main heading 
in the documentation format (Condition Values Returned) describes the 
possible condition values that the routine can return. 


1.3.2 Data in Registers RO Through R11 

Some routines return actual data in the VAX registers. The number of 
registers needed to contain the data depends on the length (or data type) 
of the information being returned. For example, a Run-Time Library 
mathematics routine that is returning the cosine of an angle as a G—floating 
point number would use registers RO and R1 because the length of a 
G—floating point number is two longwords. 

If a routine returns actual data in one or more of the registers RO through 
Rll, the returns heading in the documentation of that routine contains the 
following information: 
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VMS Usage: 
type: 
access: 
mechanism: 


floating-point 
G_floating 
write only 
by value 


For example, for the mathematics routine just discussed, the VMS data type 
is floating-point and the VAX standard data type is G—floating point. The 
meaning of the contents of the access and mechanism headings are discussed 
in Sections 1.4.3 and 1.4.4. 


In addition, under the returns heading, some text may be provided after the 
information about the type, access, and mechanism. This text explains other 
relevant information about what the routine is returning. 


For example, because the routine is returning actual data in the VAX registers, 
the registers cannot be used to convey completion status information. All 
routines that return actual data in VAX registers must signal the condition 
value, which contains the completion status. Thus, the text under the returns 
heading points out that the routine signals its completion status. 


1.3.3 Condition Values Signaled 

Although most routines return condition values in RO, some routines choose 
to signal their condition values using the VAX Signaling Mechanism. Routines 
can signal their completion status whether or not they are returning actual 
data in the VAX registers, but all routines that return actual data in the VAX 
registers must signal their completion status if they are to return this status 
information at all. 

If a routine signals its completion status, text under the returns heading 
explains this, and the Condition Values Signaled heading in the 
documentation format describes the possible condition values that the routine 
can signal. 

DIGITAL'S system routines never signal condition values indicating success. 
Only error condition values are signaled. 


1.4 Arguments Heading 

Detailed information about each argument is listed in the call format under 
the arguments heading. Arguments are described in the order in which they 
appear in the call format. If the routine has no arguments, it is indicated by 
the word "None." 

The following format is used to describe each argument: 
argument-name 

VMS Usage: VMS data type 

type: argument data type 

access: argument access 

mechanism: argument passing mechanism 

Next is a paragraph of structured text describing the arguments. Additional 
information follows, if needed. 
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1.4.1 VMS Usage Entry 


The purpose of the VMS Usage entry is to facilitate the coding of source 
language data type declarations in application programs. As mentioned 
previously, argument data types are described in two ways: 

• VMS data type 

• VAX standard data type 

Ordinarily, the VAX standard data type, discussed in Section 1.4.2, would 
be sufficient to describe the type of data passed by an argument. However, 
within the VMS operating system environment, many system routines contain 
arguments whose conceptual nature or complexity, or both, require additional 
explanation. For instance, when an argument passes the name of an array by 
reference, the type entry longword (unsigned) alone does not indicate that 
a data structure argument is being referenced. In this particular instance, an 
accompanying VMS Usage entry, denoting the VMS data type 
vector- longword-unsigned, further explains that an array of unsigned 
longwords must be declared. 

Note: The VMS Usage entry is NOT a traditional data type such as the VAX 
standard data types byte, word, longword, and so on. It is significant 
only within the context of the VMS operating system environment and is 
intended solely to expedite data declarations within application programs. 

Table A-1 in Appendix A lists possible VMS Usage entries and their 
definitions. 

See the appropriate VAX language implementation table (Tables A-2 through 
A-13) in Appendix A to determine the correct syntax of the type declaration 
in the language you are using. 


1.4.2 Type Entry 

In actuality, an argument does not have a data type; rather, the data specified 
by an argument has a data type. The argument is merely the vehicle for 
passing data to the called routine. Nevertheless, the phrase argument data 
type is used frequently to describe the data type of the data specified by 
the argument. This terminology is used because it is more simple and 
straightforward than the strictly accurate phrase data type of the data specified 
by the argument. 

Procedure calls result in the construction of an argument list on the stack. 
(This process is described in Chapter 2.) The argument list is a vector of 
longwords. The first longword on the list contains a count of the number of 
remaining longwords, and each remaining longword is one argument. Thus, 
an argument is one longword in the argument list. 

Table 1—3 lists each VAX standard data type that may appear for the type 
entry in an argument description and the VMS-defined symbolic code for 
each. These symbolic codes are used in descriptors. 

For a detailed description of each of the following symbolic codes, see 
Section 2.8. 
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Table 1-3 VAX Standard Data Types 

Data Type 

Symbolic Code 

Absolute date and time 

DSC$K_DTYPE-ADT 

Byte integer (signed) 

DSC$K_DTYPE-B 

Bound label value 

DSC$K-DTYPE-BLV 

Bound procedure value 

DSC$K-DTYPE_BPV 

Byte (unsigned) 

DSC$K-DTYPE_BU 

COBOL intermediate temporary 

DSC$K-DTYPE-CIT 

D_floating 

DSC$K-DTYPE-D 

D-floating complex 

DSC$K-DTYPE-DC 

Descriptor 

DSC$K-DTYPE-DSC 

F_floating 

DSC$K-DTYPE-F 

F_floating complex 

DSC$K_DTYPE-FC 

G—floating 

DSC$K-DTYPE-G 

G_floating complex 

DSC$K-DTYPE-GC 

H—floating 

DSC$K-DTYPE-H 

H-floating complex 

DSC$K-DTYPE-HC 

Longword integer (signed) 

DSC$K-DTYPE-L 

Longword (unsigned) 

DSC$K-DTYPE-LU 

Numeric string, left separate sign 

DSC$K-DTYPE_NL 

Numeric string, left overpunched sign 

DSC$K-DTYPE-NLO 

Numeric string, right separate sign 

DSC$K-DTYPE-NR 

Numeric string, right overpunched sign 

DSC$K-DTYPE_NRO 

Numeric string, unsigned 

DSC$K-DTYPE_NU 

Numeric string, zoned sign 

DSC$K-DTYPE-NZ 

Octaword integer (signed) 

DSC$K-DTYPE-0 

Octaword (unsigned) 

DSC$K-DTYPE-OU 

Packed decimal string 

DSC$K-DTYPE_P 

Ouadword integer (signed) 

DSC$K_DTYPE-Q 

Ouadword (unsigned) 

DSC$K-DTYPE-QU 

Character string 

DSC$K-DTYPE-T 

Aligned bit string 

DSC$K-DTYPE-V 

Varying character string 

DSC$K-DTYPE-VT 

Unaligned bit string 

DSC$K-DTYPE-VU 

Word integer (signed) 

DSC$K-DTYPE-W 

Word (unsigned) 

DSC$K-DTYPE-WU 

Unspecified 

DSC$K-DTYPE_Z 

Procedure entry mask 

DSC$K-DTYPE_ZEM 

Sequence of instruction 

DSC$K-DTYPE_ZI 
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1.4.3 Access Entry 

The access entry describes the way in which the called routine accesses 
the data specified by the argument, or access method. The following three 
methods of access are the most common: 

• Read only. Data upon which a routine operates, or data needed by the 
routine to perform its operation, must be read by the called routine. Such 
data is also called input data. When an argument specifies input data, the 
access entry is read only. 

The term only is present to indicate that the called routine does not both 
read and write (that is, modify) the input data. Thus, input data supplied 
by a variable is preserved when the called routine completes execution. 

• Write only. Data that the called routine returns to the calling routine 
must be written into a location where the calling routine can access it. 
Such data is also called output data. When an argument specifies output 
data, the access entry is write only. 

In this context, the term only is present to indicate that the called routine 
does not read the contents of the location either before or after it writes 
into the location. 

• Modify. When an argument specifies data that is both read and written 
by the called routine, the access entry is modify. In this case, the 
called routine reads the input data, which it uses in its operation, and 
then overwrites the input data with the results (the output data) of the 
operation. Thus, when the called routine completes execution, the input 
data specified by the argument is lost. 

Following is a complete list of access methods that may appear under the 
access entry in an argument description: 

• Read only 

• Write only 

• Modify 

• Function call (before return) 

• JMP after unwind 

• Call after stack unwind 

• Call without stack unwind 

For more information, see the VAX Procedure Calling and Condition 
Handling Standard in Chapter 2 of this manual. 
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1.4.4 Mechanism Entry 

The way in which an argument specifies the actual data to be used by the 
called routine is defined in terms of the argument passing mechanism. There 
are three basic passing mechanisms: 

• By value. When the longword argument in the argument list contains 
the actual data to be used by the routine, the actual data is said to be 
passed to the routine by value. In this case, the longword argument 
contains the actual data; in other words, the argument is the actual data. 
Because an argument is only one longword in length, only data that can 
be represented in one longword can be passed by value. 

• By reference. When the longword argument in the argument list contains 
the address of the data to be used by the routine, the data is said to be 
passed by reference. In this case, the argument is a pointer to the data. 

• By descriptor. When the longword argument in the argument list contains 
the address of a descriptor, the data is said to be passed by descriptor. A 
descriptor consists of two or more longwords (depending on the type of 
descriptor used) that describe the location, length, and the VAX standard 
data type of the data to be used by the called routine. In this case, the 
argument is a pointer to a descriptor that itself is a pointer to the actual 
data. 

There are several types of descriptor. Each one contains a value, or class 
type, in the fourth byte of the first longword. The class type identifies the 
type of descriptor it is. Each class type has a symbolic code. 

Table 1-4 lists each passing mechanism that may appear under the 
mechanism entry in an argument description. When the passing mechanism 
is by descriptor, the second column in Table 1-4 gives the symbolic code for 
the descriptor class type, except in the case where the passing mechanism is 
by descriptor. In this case, no symbolic code appears in column two because 
the class type of the descriptor must be determined by reading the class-type 
field of the descriptor itself. 


Table 1-4 Passing Mechanisms 

Passing Mechanism 

By value 
By reference 

By reference, array reference 
By descriptor 
By descriptor, fixed-length 
By descriptor, dynamic string 
By descriptor, array 
By descriptor, procedure 
By descriptor, decimal string 
By descriptor, noncontiguous array 
By descriptor, varying string 
By descriptor, varying string array 


Descriptor Code 


See preceding paragraph. 

DSC$K_CLASS_S 

DSC$K_CLASS_D 

DSC$K_CLASS_A 

DSC$K_CLASS_P 

DSC$K_CLASS_SD 

DSC$K_CLASS_NCA 

DSC$K_CLASS_VS 

DSC$K_CLASS_VSA 
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Table 1-4 (Cont.) Passing Mechanisms 


Passing Mechanism 

Descriptor Code 

By descriptor, unaligned bit string 

DSC$K_CLASS_UBS 

By descriptor, unaligned bit array 

DSC$K_CLASS_UBA 

By descriptor, string with bounds 

DSC$K_CLASS_SB 

By descriptor, unaligned bit string with bounds 

DSC$K CLASS UBSB 

See Section 2.9 for a 

detailed description of each descriptor class type. 


1.4.5 Explanatory Text Entry 

For each argument, one or more paragraphs of explanatory text follow the 
VMS Usage, type, access, and mechanism entries. The first paragraph is 
highly structured and always contains information in the following sequence: 

1 A sentence or a sentence fragment that describes (1) the nature of the 
data specified by the argument and (2) the way in which the routine uses 
this data. For example, if an argument were supplying a number, which 
the routine converts to another data type, the argument description would 
contain the following sentence fragment: 

Integer to be converted to an F_floating point number 

2 A sentence that expresses the relationship between the argument and the 
data that it specifies. This relationship is the passing mechanism used 

to pass the data and, for a given argument, is expressed in one of the 
following ways: 

a. If the passing mechanism is by value, the sentence should read as 
follows: 

The attrib argument is a longword that 
contains (or is) the bit mask specifying the 
attributes. 

b. If the passing mechanism is by reference, the sentence should read as 
follows: 

The objtyp argument is the address of a 
longword containing a value indicating 
whether the object is a file or a device. 

c. If the passing mechanism is by descriptor, the sentence should read 
as follows: 

The devnam argument is the address of a 
string descriptor of a logical name denoting a 
device name. 

3 Additional explanatory paragraphs that appear for each argument, as 
needed. For example, some arguments specify complex data consisting 
of many discrete fields, each of which has a particular purpose and use. 

In such cases, additional paragraphs provide detailed descriptions of each 
such field, symbolic names for the fields, if any, and guidance on their 
use. 
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1.5 Condition Values Returned Heading 

A condition value is an unsigned longword that has the following uses in the 
VAX architecture: 

• Indicates the success or failure of a called procedure 

• Describes an exception condition when an exception is signaled 

• Identifies system messages 

• Reports program success or failure to the command level 

Section 2.5 explains in detail the uses for the longword condition value and 
what it contains. Figure 2-2 depicts its format. 

The documentation heading Condition Values Returned describes the 
condition values returned by the routine when it completes execution without 
generating an exception condition. These condition values describe the 
completion status of the operation. 

If a called routine generates an exception condition during execution, the 
exception condition is signaled; the exception condition is then handled by 
a condition handler (either user-supplied or system-supplied). Depending 
on the nature of the exception condition and on the condition handler that 
handles the exception condition, the called routine either continues normal 
execution or terminates abnormally. 

If a called routine executes without generating »an exception condition, the 
called routine returns a condition value in one or two of the following four 
possible ways: 

• Condition Values Returned 

• Condition Values Returned in the I/O Status Block 

• Condition Values Returned in a Mailbox 

• Condition Values Signaled 

The method used to return the condition value is indicated under the 
Condition Values Returned heading in the documentation of each routine. 
These methods are discussed individually in the following subsections. 

Under these headings, a 2-column list shows the S 3 nnbolic code for each 
condition value the routine can return and an accompanying description. The 
description explains whether the condition value indicates success or failure 
and, if failure, what user action may have caused the failure and what you 
can do to correct it. Condition values that indicate success are listed first. 

Symbolic codes for condition values are defined by the system. The symbolic 
code defined for each condition value equates to a number that is identical 
to the longword condition value when interpreted as a number. In other 
words, though the condition value consists of several fields, each of which 
can be interpreted individually for specific information, the entire longword 
condition value itself can be interpreted as an unsigned longword integer, and 
this integer has an equivalent symbolic code. 

The following three subsections discuss the ways in which the called routine 
returns condition values. 
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1.5.1 Condition Values Returned 

The possible condition values that the called routine can return in general 
register RO are listed under the Condition Values Returned heading in the 
documentation. Most routines return a condition value in this way. 

In the documentation of system services that complete asynchronously, both 
the Condition Values Returned and Condition Values Returned in the I/O 
Status Block are used. Under the Condition Values Returned heading, the 
condition values returned by the asynchronous service refer to the success 
or failure of the system service request—that is, to the status associated 
with the correctness of the syntax of the call, in contrast to the final status 
associated with the completion of the service operation. For asynchronous 
system services, condition values describing the success or failure of the actual 
service operation—that is, the final completion status—are listed under the 
Condition Values Returned in the I/O Status Block heading. 


1.5.2 Condition Values Returned in the I/O Status Block 

The possible condition values that the called routine can return in an I/O 
status block are listed under the Condition Values Returned in the I/O Status 
Block heading in the documentation. 

The routines that return condition values in the I/O status block are 
the system services that are completed asynchronously. Each of these 
asynchronous system services returns to the caller as soon as the service 
call is queued. This allows the continued use of the calling program during 
the execution of the service operations. System services that are completed 
asynchronously all have arguments that specify an I/O status block. When 
the system service operation is completed, a condition value specifying the 
completion status of the operation is written in the first word of this I/O 
status block. 

Representing a longword condition value in a word-length field is possible for 
system services because the high-order word in all system service condition 
values is 0. Section 2.5 explains in detail what the fields contain in the 
longword condition value. 


1.5.3 Condition Values Returned in a Mailbox 

The possible condition values that the called routine can return in a mailbox 
are listed under the Condition Values Returned in a Mailbox heading. 

Routines such as SYS$SNDOPR that return condition values in a mailbox 
send information to another process to perform a task. The receiving process 
performs the action and returns the status of the task to the mailbox of the 
sending process. 
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1.5.4 Condition Values Signaled 

The possible condition values that the called routine can signal (instead of 
returning them in RO) are listed under the Condition Values Signaled heading. 

Routines that signal condition values as a way of indicating the completion 
status do so because these routines are returning actual data in one or more 
of the general registers. Because register RO is used to convey data, it cannot 
also.,receive the condition value. 

As mentioned, the signaling of condition values occurs whenever a routine 
generates an exception condition, regardless of how the routine returns its 
completion status under normal circumstances. 
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Introduction 

The VAX Procedure Calling Standard is used with the VAX hardware 
procedure-calling mechanism. This standard applies to the following: 

• All externally callable interfaces in DlGlTAL-supported, standard system 
software 

• All intermodule calls to major VAX components 

• All external procedure calls generated by standard DIGITAL language 
processors 

This standard does not apply to calls to internal (local) routines or to 
language-support routines. Within a single module, the language processor 
or programmer can use a variety of other linkage and argument-passing 
techniques. 

The standard defines mechanisms for passing arguments by immediate value, 
by reference, and by descriptor. However, the immediate value mechanism is 
intended for use only by VMS system services and within programs written 
in VAX BLISS or VAX MACRO. 

The procedure call mechanism depends on agreement between the calling 
and called procedures to interpret the argument list. The argument list does 
not fully describe itself. This standard requires language extensions to permit 
a calling program to generate some of the argument-passing mechanisms 
expected by called procedures. 

This standard specifies the following attributes of the interfaces between 
modules: 

• Calling sequence—the instructions at the call site and at the entry point 

• Argument list—the structure of the list describing the arguments to the 
called procedure 

• Function value return—the form and conventions for the return of the 
function value as a value or as a condition value to indicate success or 
failure 

• Register usage—which registers are preserved and who is responsible for 
preserving them 

• Stack usage—rules governing the use of the stack 

• Argument data types—the data types of arguments that can be passed 

• Argument descriptor formats—how descriptors are passed for the more 
complex arguments 
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• Condition handling—how exception conditions are signaled and how 
they can be handled in a modular fashion 

• Stack unwinding—how the current thread of execution can be aborted 
efficiently 


2.1.1 Goals of the Calling Standard 

When the VAX Procedure Calling Standard was developed, the following 

goals were kept in mind: 

• The standard must be applicable to all intermodule callable interfaces in 
the VAX software system. Specifically, the standard must consider the 
requirements of VAX MACRO, VAX BLISS, VAX BASIC, VAX COBOL, 
VAX CORAL, VAX FORTRAN, VAX PASCAL, VAX PEARL, VAX PL/I, 
VAX RPG II, and calls to the operating system and library procedures. 
The needs of other languages that DIGITAL may support in the future 
must be met by the standard or by compatible revision of it. 

• The standard should not include capabilities for lower-level components 
(such as VAX BLISS, VAX MACRO, operating system) that cannot be 
invoked from the higher-level languages. 

• The calling program and called procedure should be writable in different 
languages. The standard attempts to reduce the need for use of language 
extensions for mixed-language programs. 

• The procedure mechanism must be sufficiently economical in both space 
and time to be usable as the only calling mechanism within VAX. 

• The standard should contribute to the writing of error-free, modular, 
and maintainable software. Effective sharing and reuse of VAX software 
modules are significant goals. 

• The standard must allow the called procedure to have a variety of 
techniques for argument handling. Specifically, the called procedure must 
be able to do the following: 

— Reference arguments indirectly through the argument list 
— Copy atomic data types, strings, and arrays 
— Copy addresses of atomic data types, strings, and arrays 

• The standard should provide you with some control over fixing, reporting, 
and controlling flow on hardware and software exceptions. 

• The standard should provide subsystem and application writers with 
the ability to override system messages to provide a more suitable 
application-oriented interface. 

• The standard should add no space or time overhead to procedure calls 
and returns that do not establish handlers and should minimize time 
overhead for establishing handlers at the cost of increased time overhead 
when exceptions occur. 


2-2 






VAX Procedure Calling and Condition Handling Standard 



Some possible attributes of a procedure-calling mechanism were considered 
and rejected. Specific attributes rejected for the VAX procedure-calling 
mechanism include the following: 

• The procedure mechanism need not provide complete checking of 
argument data types, data structures, and parameter access. The VAX 
protection and memory-management system is not dependent upon 
correct interactions between user-level calling and called procedures. 
Such extended checking may be desirable in some circumstances, but 
system integrity is not dependent upon it. 

• The VAX procedure mechanism need not provide complete information 
for an interpretive VMS Debugger. The definition of the debugger 
includes a debug symbol table (DST) that contains the required 
descriptive information. 


2.1.2 Definitions Used in the VAX Calling Standard 

A procedure is a closed sequence of instructions that is entered from and 
returns control to the calling program. 

A function is a procedure that returns a single value in accordance with the 
standard conventions for value returning. If additional values are returned, 
they are returned by means of the argument list. 

A subroutine is a procedure that returns a known value not in accordance 
with the standard conventions for value returning. If values are returned, 
they are returned by means of the argument list. 

An address is a 32-bit VAX address positioned in a longword item. 

An argument list is a vector of longwords that represents a procedure 
parameter list and possibly a function value. 

Immediate value is a mechanism for passing input parameters where the 
actual value is provided in the longword argument list entry by the calling 
program. 

Reference is a mechanism for passing parameters where the address of the 
parameter is provided in the longword argument list by the calling program. 

Descriptor is a mechanism for passing parameters where the address of a 
descriptor is provided in the longword argument list entry. The descriptor 
contains the address of the parameter, the data type, size, and additional 
information needed to describe fully the data passed. 

An exception condition is a hardware- or software-detected event that alters 
the normal flow of instruction execution. It usually indicates a failure. 

A condition value is a 32-bit value used to identify uniquely an exception 
condition. A condition value may be returned to a calling program as a 
function value or signaled using the VAX signaling mechanism. 

Language support procedures are called implicitly to implement higher-level 
language constructs. They are not intended to be called explicitly from user 
programs. 

Library procedures are called explicitly using the equivalent of a CALL 
statement or function reference. They are usually language independent. 
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2.2 Calling Sequence 

At the option of the calling program, you invoke the called procedure using 
either the CALLG or CALLS instruction, as follows: 

CALLG argist, proc 

CALLS argent, proc 

CALLS pushes the argument count argent onto the stack as a longword and 
sets the argument pointer, AP, to the top of the stack. The complete sequence 
using CALLS is as follows: 

push argn 


push argl 

CALLS #n, proc 

If the called procedure returns control to the calling program, control must 
return to the instruction immediately following the CALLG or CALLS 
instruction. Skip returns and GOTO returns are allowed only during stack 
unwind operations. 

The called procedure returns control to the calling program by executing the 
return instruction, RET. 


2.3 Argument List 


The argument list is the primary means of passing information to and 
receiving results from a procedure. 

2.3.1 Argument List Format 

Figure 2-1 shows the argument list format. 

Figure 2-1 Argument List Format 



The first longword is always present and contains the argument count as 
an unsigned integer in the low byte. The 24 high-order bits are reserved 
to DIGITAL and must be zero. To access the argument count, the called 
procedure must ignore the reserved bits and access the count as an unsigned 
byte (for example, MOVZBL, TSTB, or CMPB). 
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The remaining longwords can be one of the following: 

• An uninterpreted 32-bit value (by immediate value mechanism). If the 
called procedure expects fewer than 32 bits, it accesses the low-order bits 
and ignores the high-order bits. 

• An address (by reference mechanism). It is typically a pointer to a scalar 
data item, an array, a structure, a record, or a procedure. 

• An address of a descriptor (by descriptor mechanism). See Section 2.9 for 
descriptor formats. 

The standard permits programs to call by immediate value, by reference, 
by descriptor, or combinations of these mechanisms. Interpretation of 
each argument list entry depends on agreement between the calling and 
called procedures. Higher-level languages use the reference or descriptor 
mechanisms for passing input parameters. VMS system services and VAX 
MACRO or VAX BLISS programs use all three mechanisms. 

A procedure with no arguments is called with a list consisting of a 0 argument 
count longword, as follows: 

CALLS #0. proc 

A missing or null argument—for example, CALL SUB(A„B)—is represented 
by an argument list entry consisting of a longword 0. Some procedures allow 
trailing null arguments to be omitted, others require all arguments. See each 
procedure's specification for details. 

The argument list must be treated as read-only data by the called procedure 
and may be allocated in read-only memory at the option of the calling 
program. 


2.3.2 Argument Lists and Higher-Level Languages 

Functional notations for procedure calls in higher-level languages are mapped 

into VAX argument lists according to the following rules: 

• Arguments are mapped from left to right to increasing argument list 
offsets. The left-most (first) argument has an address of arglst+4; the next 
has an address of arglst+8, and so on. The only exception to this is when 
arglst-i4 specifies where a function value is to be returned, in which case 
the first argument has an address of arglst+8; the second argument has an 
address of arglst+12, and so on. See Section 2.4 for more information. 

• Each argument position corresponds to a single VAX argument list entry. 
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2.3.2.1 Order of Argument Evaluation 

Because most higher-level languages do not specify the order of evaluation 
of arguments (with respect to side effects), those language processors can 
evaluate arguments in any convenient order. 

In constructing an argument list on the stack, a language processor can 
evaluate arguments from right to left and push their values on the stack. If 
call-by-reference semantics are used, argument expressions can be evaluated 
from left to right, with pointers to the expression values or descriptors being 
pushed from right to left. 

The choice of argument evaluation order and code generation strategy is 
constrained only by the definition of the particular language. You should not 
write programs that depend on the order of evaluation of arguments. 


2.3.2.2 Language Extensions for Argument Transmission 

The VAX Procedure Calling Standard permits arguments to be passed by 
immediate value, by reference, or by descriptor. By default, all language 
processors, except VAX MACRO and VAX BLISS, pass arguments by reference 
or by descriptor. 

Language extensions are needed to reconcile the different argument-passing 
mechanisms. In addition to the default passing mechanism used, each 
language processor is required to give you explicit control, in the calling 
program, of the argument-passing mechanism for the data types supported by 
the language. 

The value Yes means the language processor is required to provide the user 
explicit control of that passing mechanism. 


Data Type 

Section 

Value 

Reference 

Descriptor 

Atomic <= 32 bits 

2.8.1 

Yes 

Yes 

Yes 

Atomic > 32 bits 

2.8.1 

No 

Yes 

Yes 

String 

2.8.2 

No 

Yes 

Yes 

Miscellaneous 

2.8.3 

No’ 

No 

No 

Array 

2.9 

No 

Yes 

Yes 


^For those languages supporting the bound procedure value data type, a language 
extension is required to pass it by immediate value in order to be able to interface with 
VMS system services and other software. See Section 2.8.3 


For example, VAX FORTRAN provides the following intrinsic compile-time 
functions: 

%VAL(arg) By immediate value mechanism. Corresponding argument list 

entry is the 32-bit value of the argument, arg, as defined in the 
language. 

%REF(arg) By reference mechanism. Corresponding argument list entry 

contains the address of the value of the argument, arg, as 
defined in the language. 
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%DESCR(arg) By descriptor mechanism. Corresponding argument list entry 

contains the address of a VAX descriptor of the argument, arg, 
as defined in Section 2.9 and in the language. 

You can use these intrinsic functions in the syntax of a procedure call to 
control generation of the argument list. For example; 

CALL SUBl(y.VAL(123) . ’/.REFCX), %DESCR(A)) 

In other languages the same effect might be achieved by making appropriate 
attributes of the declaration of SUBl in the calling program. Thus, you might 
write the following after making the external declaration for SUBl: 

CALL SUBl (123, X, A) 


2.4 Function Value Return 

A function value is returned in register RO if its data type can be represented 
in 32 bits, or in registers RO and R1 if its data type can be represented in 64 
bits, provided the data type is not a string data type (see Section 2.8.2). 

If the data type requires fewer than 32 bits, then R1 and the high-order bits 
of RO are undefined. If the data type requires 32 or more bits but fewer than 
64 bits, then the high-order bits of R1 are undefined. Two separate 32-bit 
entities cannot be returned in RO and R1 because higher-level languages 
cannot process them. 

In all other cases (the function value needs more than 64 bits, the data type is 
a string, the size of the value can vary from call to call, and so on) the actual 
argument list and the formal argument list are shifted one entry. The new, 
first entry is reserved for the function value. In this case, one of the following 
mechanisms is used to return the function value: 

• If the maximum length of the function value is known (for example, 
octaword integer, H—floating, or fixed-length string), the calling program 
can allocate the required storage and pass the address of the storage or a 
descriptor for the storage as the first argument. 

• If the maximum length of a string function value is not known to the 
calling program, the calling program can allocate a dynamic string 
descriptor. The called procedure then allocates storage for the function 
value and updates the contents of the dynamic string descriptor using 
VAX Run-Time Library procedures. See Section 2.9.3. 

Some procedures, such as operating system calls and many library procedures, 
return a success/failure value as a longword function value in RO. Bit <0> 
of the value is set (Boolean true) for a success and clear (Boolean false) for a 
failure. The particular success or failure status is encoded in the remaining 31 
bits, as described in Section 2.5. 
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2.5 Condition Value 

The VAX architecture uses condition values for the following reasons: 

• To indicate the success or failure of a called procedure as a function value 

• To describe an exception condition when an exception is signaled 

• To identify system messages 

• To report program success or failure to the command language level 

A condition value is a longword that includes fields to describe the software 
component generating the value, the reason the value was generated, and the 
error severity status. Figure 2-2 shows the format of the condition value. 

Figure 2-2 Format of the Condition Value 
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condition identification 


severity 
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Fields in the Condition Value 
condition identification 

Identifies the condition uniquely on a systemwide basis. 

facility 

Identifies the software component generating the condition value. Bit <27> 
is set for customer facilities and clear for DIGITAL facilities. 

message number 

Describes the status, which can be a hardware exception that occurred or a 
software-defined value. Message numbers with bit <15> set are specific 
to a single facility. Message numbers with bit <15> clear are systemwide 
status codes. 

severity 

Indicates success or failure. The severity code bit <0> is set for success 
(logical true) and clear for failure (logical false); bits <1> and <2> 
distinguish degrees of success or failure. Bits <2:0> , when taken as an 
unsigned integer, are interpreted as shown in the following table. 
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Symbol 

Value 

Description 


STS$K_WARNING 

0 

Warning 


STS$K_SUCCESS 

1 

Success 


STS$K_ERROR 

2 

Error 


STS$K_INFO 

3 

Information 


STS$K_SEVERE 

4 

Severe._error 



5 

Reserved by DIGITAL 


6 

Reserved by DIGITAL 


7 

Reserved by DIGITAL 


Section 2.5.1 describes the severity code more fully. 

cntrl 

Controls the printing of the message associated with the condition value. Bit 
<28> inhibits the message associated with the condition value from being 
printed by the SYS$EXIT system service. This bit is set by the system default 
handler after it has output an error message using the SYS$PUTMSG system 
service. It should also be set in the condition value returned by a procedure 
as a function value, if the procedure has also signaled the condition (so that 
the condition has been either printed or suppressed). Bits <31:29> must be 
zero; they are reserved by DIGITAL for future use. 

Software symbols are defined for these fields, as follows: 


Symbol 

Value 

Meaning 

Field 

STS$V_COND_ID 

3 

Position of 27:3 

Condition identification 

STS$S_COND_ID 

25 

Size of 27:3 

Condition identification 

STS$M_COND_ID 

Mask 

Mask for 27:3 

Condition identification 

STS$V_INHIB_MSG 

1@28 

Position for 28 

Inhibit message on 
image exit 

STS$S_INHIB_MSG 

1 

Size for 28 

Inhibit message on 
image exit 

STS$M_INHIB_MSG 

Mask 

Mask for 28 

Inhibit message on 
image exit 

STS$V_FAC_NO 

16 

Position of 27:16 

Facility number 

STS$S_FAC_NO 

12 

Size of 27:16 

Facility number 

STS$M_FAC_NO 

Mask 

Mask for 27:16 

Facility number 

STS$V_CUST_DEF 

27 

Position for 27 

Customer facility 

STS$S_CUST_DEF 

1 

Size for 27 

Customer facility 

STS$M_CUST_DEF 

1@27 

Mask for 27 

Customer facility 

STS$V_MSG_NO 

3 

Position of 15:3 

Message number 

STS$S_MSG_NO 

13 

Size of 15:3 

Message number 

STS$M_MSG_NO 

Mask 

Mask for 15:3 

Message number 

STS$V_FAC_SP 

15 

Position of 15 

Facility specific 
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Symbol 

Value 

Meaning 

Field 

STS$S_FAC_SP 

1 

Size for 15 

Facility specific 

STS$M_FAC_SP 

1@15 

Mask for 15 

Facility specific 

STS$V_CODE 

3 

Position of 14:3 

Message code 

STS$S_CODE 

12 

Size of 14:3 

Message code 

STS$M_CODE 

Mask 

Mask for 14:3 

Message code 

STS$V_SEVERITY 

0 

Position of 2:0 

Severity 

STS$S_SEVERITY 

3 

Size of 2:0 

Severity 

STS$M_SEVERITY 

7 

Mask for 2:0 

Severity 

STS$V_SUCCESS 

0 

Position of 0 

Success 

STS$S_SUCCESS 

1 

Size of 0 

Success 

STS$M_SUCCESS 

1 

Mask for 0 

Success 


2.5.1 Interpretation of Severity Codes 

A severity code of 0 indicates a warning. This code is used whenever a 
procedure produces output but the output produced may not be what the 
user expected, for example, a compiler modification of a source program. 

A severity code of 1 indicates that the procedure generating the condition 
value completed successfully, as expected. 

A severity code of 2 indicates that an error has occurred, but that the 
procedure did produce output. Execution can continue, but the results 
produced by the component generating the condition value are not all correct. 

A severity code of 3 indicates that the procedure generating the condition 
value completed successfully, but has some parenthetical information to be 
included in a message if the condition is signaled. 

A severity code of 4 indicates that a severe error occurred and the component 
generating the condition value was unable to produce output. 

When designing a procedure, you should base the choice of severity code for 
its condition values on the following default interpretations: 

• The calling program typically performs a low-bit test, so it treats 
warnings, errors, and severe errors as failures, and success and 
information as successes. 

• If the condition value is signaled (see Section 2.11.3), the default handler 
treats severe errors as reason to terminate and all the others as the basis 
for attempting to continue. 

• When the program image exits, the command interpreter by default treats 
errors and severe errors as the basis for stopping the job, and warnings, 
information, and successes as the basis for continuing. 
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The following table summarizes the default interpretation of condition values. 


Severity 

Routine 

Signal 

Default at 

Program Exit 

Success 

Normal 

Continue 

Continue 

Information 

Normal 

Continue 

Continue 

Warning 

Failure 

Continue 

Continue 

Error 

Failure 

Continue 

Stop job 

Severe error 

Failure 

Exit 

Stop job 


The default for signaled messages is to output a message to SYS$OUTPUT. In 
addition, for severities other than success (STS$K-.SUCCESS), a copy of the 
message is made on SYS$ERROR. At program exit, success and information 
completion values do not generate messages; however, warning, error, and 
severe error condition values do generate messages to both SYS$OUTPUT 
and SYS$ERROR, unless bit <28> (STS$V_INHIB_MSG) is set. 

Unless there is a good basis for another choice, a procedure should use either 
success or severe error as its severity for each condition value. 


2.5.2 Use of Condition Values 

VAX software components return condition values when they complete 
execution. When a severity code of warning, error, or severe error is 
generated, the status code describes the nature of the problem. This value can 
be tested to change the flow of control of a procedure or be used to generate 
a message, or both. 

User procedures can also generate condition values to be examined by other 
procedures and by the command interpreter. User-generated condition values 
should have bits <27> and <15> set so that they do not conflict with 
values generated by DIGITAL. 


2.6 Register Usage 

The following registers have defined uses: 


Register Use 

PC Program counter. 

SP Stack pointer. 

FP Current stack frame pointer. It must always point at the current 

frame. No modification is permitted within a procedure body. 


2-11 










VAX Procedure Calling and Condition Handling Standard 


AP Argument pointer. When a call occurs, AP must point to a valid 

argument list. A procedure without parameters points to an 
argument list consisting of a single longword containing the value 0 . 

R1 Environment value. When a procedure that needs an environment 

value Is called, the calling program must set R1 to the environment 
value. See bound procedure value In Section 2.8.3. 

R0,R1 Function value return registers. These registers are not to be 

preserved by any called procedure. They are available as temporary 
registers to any called procedure. 


Registers R2 through Rll are to be preserved across procedure calls. The 
called procedure can use these registers, provided it saves and restores them 
using the procedure entry mask mechanism. The entry mask mechanism 
must be used so that any stack unwinding done by the condition-handling 
mechanism restores all registers correctly. In addition, PC, SP, FP, and AP 
are always preserved by the CALL instructions and restored by the RET 
instruction. However, a called procedure can use AP as a temporary register. 


2.7 Stack Usage 

Figure 2-3 shows the contents of the stack frame that is created for the called 
procedure by the CALLG or CALLS instruction. 


Figure 2-3 Stack Frame Generated by CALLG and CALLS 
Instructions 


condition handler (0) :(SP):(FP)) 

mask/PSW 

AP 

FP 

PC 

R2 (optional) 


Rll (optional) 


FP always points at the condition handler longword of the stack frame. Other 
uses of FP within a procedure are prohibited. See Section 2.10 for more 
information. 

The contents of the stack located at addresses higher than the mask/PSW 
longword belong to the calling program; they should not be read or written 
by the called procedure, except as specified in the argument list. The contents 
of the stack located at addresses lower than SP belong to interrupt and 
exception routines; they are modified continually and unpredictably. 

The called procedure allocates local storage by subtracting the required 
number of bytes from the SP provided on entry. This local storage is freed 
automatically by the RET instruction. 

Bit <28> of the mask/PSW longword is reserved by DIGITAL for future 
extensions to the stack frame. 
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2.8 Argument Data Types 

Each data type implemented for a higher-level language uses one of the 
following VAX data types for procedure parameters and elements of file 
records: 

• Atomic 

• String 

• Miscellaneous 

When existing data types are not sufficient to satisfy the semantics of a 
language, new data types are added to this standard, including certain 
language-specific ones. These data types can generally be passed by 
immediate value (if 32 bits or less), by reference, or by descriptor. 

You use the encoding given in Sections 2.8.1 and 2.8.2 whenever you need to 
identify data types, such as in a descriptor. However, in addition to their use 
in descriptors, these data type codes are also useful in areas outside the scope 
of the Procedure Calling Standard for identifying VAX data types. Therefore, 
each data type code indicates a unique data format independent of its use in 
descriptors. 

Some data types are composed of a record-like structure consisting of two or 
more elementary data types. For example, the F_floating complex (FC) data 
type is made up of two F__floating data types, and the varying character string 
(VT) data type is made up of a word (unsigned, WU) data type followed by a 
character string (T) data type. 

Unless stated -otherwise, all data types represent signed quantities. The 
unsigned quantities throughout this standard do not allocate space for the 
sign; all bit or character positions are used for significant data. 


2.8.1 Atomic Data Types 

Table 2-1 shows how atomic data types are defined and encoded. 


Table 2-1 Atomic Data Types 

Symbol Code Name/Description 


DSC$K_DTYPE_Z 0 

DSC$K_DTYPE_BU 2 

DSC$K_DTYPE_WU 3 

DSC$K_DTYPE_LU 4 


Unspecified 

The calling program has specified no data 
type. The default argument for the called 
procedure should be the correct type. 

Byte (unsigned) 

8-bit unsigned quantity. 

Word (unsigned) 

16-bit unsigned quantity. 

Longword (unsigned) 

32-bit unsigned quantity. 
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Table 2-1 (Cont.) 

Atomic Data Types 

Symbol 

Code 

Name/Description 

DSC$K_DTYPE_QU 

5 

Quadword (unsigned) 

64-bit unsigned quantity. 

DSC$K_DTYPE_OU 

25 

Octaword (unsigned) 

128-bit unsigned quantity. 

DSC$K_DTYPE_B 

6 

Byte integer (signed) 

8-bit signed 2's-complement integer. 

DSC$K_DTYPE_W 

7 

Word integer (signed) 

16-bit signed 2"s-complement integer. 

DSC$K_DTYPE_L 

8 

Longword integer (signed) 

32-bit signed 2's-complement integer. 

DSC$K_DTYPE_Q 

9 

Quadword integer (signed) 

64-blt signed 2's-complement integer. 

DSC$K_DTYPE_0 

26 

Octaword integer (signed) 

128-bit signed 2's-complement integer. 

DSC$K_DTYPE_F 

10 

F_floating 

32-bit F_floating quantity representing a 
single-precision number. 

DSC$K_DTYPE_D 

11 

□—floating 

64-bit D—floating quantity representing a 
double-precision number. 

DSC$K_DTYPE_G 

27 

G—floating 

64-bit G—floating quantity representing a 
double-precision number. 

DSC$K_DTYPE_H 

28 

H—floating 

128-bit H—floating quantity representing a 
quadruple-precision number. 

DSC$K_DTYPE_FC 

12 

F—floating complex 

Ordered pair of F_floating quantities, 
representing a single-precision complex 
number. The lower addressed quantity is the 
real part, the higher addressed quantity Is the 
imaginary part. 

DSC$K_DTYPE_DC 

13 

□—floating complex 


Ordered pair of D_floating quantities, 
representing a double-precision complex 
number. The lower addressed quantity is the 
real part, the higher addressed quantity is the 
imaginary part. 
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Table 2-1 (Cont.) 

Atomic Data Types 

Symbol 

Code 

Name/Description 

DSC$K_DTYPE_GC 

29 

G_floatlng complex 

Ordered pair of G_floating quantities, 
representing a double-precision complex 
number. The lower addressed quantity Is the 
real part, the higher addressed quantity is the 
imaginary part. 

DSC$K_DTYPE_HC 

30 

H_floating complex 

Ordered pair of H_floating quantities, 
representing a quadruple-precision complex 
number. The lower addressed quantity Is the 
real part, the higher addressed quantity is the 
imaginary part. 

DSC$K_DTYPE_CIT 

31 

COBOL Intermediate Temporary 

A floating-point datum with an 18-digit 
normalized decimal fraction and a 2-decimal- 
digit exponent. The fraction is a packed 
decimal string. The exponent is a 16-blt 
2's-complement integer. See Section 2.8.6 
for details. 


2.8.2 String Data Types 

String data types are ordinarily described by a string descriptor. Table 2-2 
shows how the string data types are defined and encoded. 


Table 2-2 String Data Types 


Symbol 

Code 

Name/Description 

DSC$K_DTYPE_T 

14 

Character string 



A single 8-bit character (atomic data type) 
or a sequence of 0 to 2^®-1 8-bit characters 



(string data type). 

DSC$K_DTYPE_VT 

37 

Varying character string 


A 16-bit unsigned count of the current 
number of 8-bit characters following, 
followed by a sequence of 0 to 2^®-1 8- 
bit characters (see Section 2.8.7 for details). 
When this data type is used with descriptors, 
it can only be used with the varying string 
and varying string array descriptors because 
the length field is interpreted differently 
from the other 8-blt string data types. (See 
Sections 2.8.7, 2.9.12, and 2.9.13 for 
further discussion.) 

DSC$K_DTYPE_NU 15 Numeric string, unsigned 

DSC$K_DTYPE_NL 16 Numeric string, left separate sign 
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Table 2-2 (Cent.) String Data Types 

Symbol Code Name/Description 


DSC$K_DTYPE_NLO 17 
DSC$K_DTYPE_NR 18 
DSC$K_DTYPE_NRO 19 
DSC$K_DTYPE_NZ 20 
DSC$K_DTYPE_P 21 
DSC$K_DTYPE_V 1 


DSC$K_DTYPE_VU 34 


Numeric string, left overpunched sign 
Numeric string, right separate sign 
Numeric string, right overpunched sign 
Numeric string, zoned sign 
Packed-decimal string 
Aligned bit string 

A string of 0 to 2^®-1 contiguous bits. 

The first bit is bit <0> of the first byte, 
and the last bit is any bit in the last byte. 
Remaining bits in the last byte must be zero 
on read and are cleared on write. Unlike the 
unaligned bit string (VU) data type, when 
the aligned bit string (V) data type is used 
in array descriptors, the ARSIZE field is in 
units of bytes, not bits, because allocation is 
a multiple of 8 bits. 

Unaligned bit string 

The data is 0 to 2^®-1 contiguous bits 
located arbitrarily with respect to byte 
boundaries. See also aligned bit string (V) 
data type. Because additional information is 
required to specify the bit position of the first 
bit, this data type can be used only with the 
unaligned bit string and unaligned bit array 
descriptors (see Sections 2.9.14 
and 2.9.15). 


2.8.3 Miscellaneous Data Types 

Table 2-3 shows how miscellaneous data types are defined and encoded. 

Table 2—3 Miscellaneous Data Types 


Symbol 

Code 

Name/Description 

DSC$K_DTYPE_ZI 

22 

Sequence of Instructions 

DSC$K_DTYPE_ZEM 

23 

Procedure entry mask 

DSC$K_DTYPE_DSC 

24 

Descriptor 


This data type allows a descriptor to be a data 
type; thus, levels of descriptors are allowed. 
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Table 2-3 (Cent.) Miscellaneous Data Types 

Symbol Code Name/Description 

DSC$K_DTYPE_BPV 32 Bound procedure value 

A 2-longword entity in which the first 
longword contains the address of a procedure 
entry mask and the second longword is the 
environment value. The environment value 
is determined in a language-specific manner 
when the original bound procedure value is 
generated. When the bound procedure is 
called, the calling program loads the second 
longword into Rl. When the environment 
value is not needed, this data type can be 
passed using the immediate value mechanism. 
In this case, the argument list entry contains 
the address of the procedure entry mask and 
the second longword is omitted. 

DSC$K_DTYPE_BLV 33 Bound label value 

A 2-longword entity in which the first 
longword contains the address of an 
instruction and the second longword is the 
language-specific environment value. The 
environment value is determined in a language- 
specific manner when the original bound label 
value is generated. 

DSC$K_DTYPE_ADT 35 Absolute date and time 

A 64-blt unsigned, scaled, binary integer 
representing a date and time in 100- 
nanosecond units offset from the VMS 
operating system base date and time, 
which is 00:00 o'clock, November 17, 

1858 (the Smithsonian base date and time 
for astronomical calendars). The value zero 
indicates that the date and time have not been 
specified, so a default value or distinctive print 
format may be used. 

Note that the ADT data type is the same as 
the VMS date format for positive values only. 


2.8.4 Facility-Specific Data Type Codes 

Data type codes 160 through 191 are reserved by DIGITAL for facility-specific 
purposes. These codes must not be passed between facilities because different 
facilities may use the same code for different purposes. These codes may 
be used by compiler-generated code to pass parameters to the language- 
specific run-time support procedures associated with that language or the 
VMS Debugger. 
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2.8.5 Reserved Data Type Codes 

The type codes 38 through 191 are reserved by DIGITAL. Codes 192 through 
255 are reserved for DIGITAL's Computer Special Systems Group and for 
customers for their own use. 


2.8.6 COBOL Intermediate Temporary Data Type 

A COBOL intermediate temporary datum is 12 contiguous bytes starting on 
an arbitrary byte boundary. It is specified by its address, A. 


A 

A + 2 
A + 4 
A -f 6 
A + 8 
A + 10 
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A COBOL intermediate temporary datum represents a floating-point datum 
with a normalized, 18-digit, packed-decimal fraction and a 16-bit 2's- 
complement integer exponent. Bytes 0 and 1 are the exponent. Bytes 2 
through 11 contain the normalized packed-decimal fraction. The sign of the 
datum is the sign of the fraction. If the fraction is zero, the value of the 
datum is zero. 

If the exponent is from -99 to +99, operations can be performed on this 
datum. If the exponent is outside this range, a reserved operand condition 
is signaled (see Section 2.12). If a calculated datum has an exponent greater 
than +99, the exact result with the low-order 15 bits of the true exponent is 
stored in the result datum and an overflow condition is signaled. 

If a calculated datum has an exponent less than -99, the exact result with 
the low-order 15 bits of the true exponent is stored in the result datum 
and an underflow condition is signaled. The condition handler can take 
the appropriate action. Condition mnemonics have a COB$_ prefix and 
are documented with the COBOL part of the VMS Run-Time Library. An 
exponent value of -32768 is taken as reserved and should be used to encode 
reserved operands such as uninitialized datum and indeterminate value. By 
convention, if the fraction of a result is zero, the exponent is set to zero. 
Fractions are generated with preferred sign codes and avoid minus zero. 


111111 


5 4 3 2 

10 9 8 

7 6 5 4 

3 2 10 

exponent 

f<16> 

f<15> 

0 

f<17> 

f<12> 

f<11> 

f<14> 

f<13> 

f<8> 

f<7> 

f<10> 

f<9> 

f<4> 

f<3> 

f<6> 

f<5> 

f<0> 

sign 

f<2> 

f<1> 
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2.8.7 Varying Character String Data Type {DSC$K_DTYPE_VT) 

The varying character string data type consists of the following two fixed- 
length areas allocated contiguously with no padding in between: 

CURLEN An unsigned word specifying the current length in bytes of the 
immediately following string (byte aligned). 

BODY A fixed-length area containing the string that can vary from zero to 
a maximum length defined for each instance of string. The range of 
this maximum length Is 0 to 

When passed by reference or by descriptor, the address of the varying 
character string (VT) data type is always the address of the CURLEN field, 
not the BODY field. 

When a called procedure modifies a varying character string data type passed 
by reference or by descriptor, it writes the new length, n, into CURLEN and 
may modify all bytes of BODY. 

For example, consider a varying string with a maximum length of seven 
characters. For the representation of the string, ABC, CURLEN would be 
three and the last four bytes would be undefined, as follows: 



7 0 
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2.9 Argument Descriptor Formats 

A uniform descriptor mechanism is defined for use by all procedures that 
conform to the VAX Procedure Calling Standard. Descriptors are self 
describing, and the mechanism is extensible. When existing descriptors 
are not sufficient to satisfy the semantics of a language, new descriptors are 
added to this standard. 

Unless stated otherwise, the calling program fills in all fields in descriptors. 
This is true whether the descriptor is generated by default or by a language 
extension. The fields are filled in even if a called procedure written in the 
same language would ignore the contents of some of the fields. 
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A descriptor conforms to the VAX Procedure Calling Standard if all fields are 
filled in by the calling program according to the standard, even if the field is 
not needed by the called program. 

Note: Unless stated otherwise, all fields in descriptors represent unsigned 

quantities, are read-only from the point of view of the called procedure, 
and may be allocated in read-only memory at the option of the calling 
program. 

If a language processor implements a language-specific data type that is not 
added to this standard (see Section 2.8), it is not required to use a standard 
descriptor to pass an array of such a data type. However, if a language 
processor does pass an array of such a data type using a standard descriptor, 
the language processor fills in the DSC$B_DTYPE field with zero, indicating 
that the data type field is unspecified, rather than using a more general data 
type code. 

For example, an array of PL/I POINTER data types has the DTYPE field 
filled in with the value 0 (unspecified data type) rather than with the value 
4 (longword (unsigned) data type). The remaining fields are filled in as 
specified by this standard; for example, DSC$W_LENGTH is filled in with 
the size in bytes. Because the language-specific data type may be added to 
the standard in the future, generic application procedures that examine the 
DTYPE field should be prepared for zero and for additional data types. 


2.9.1 Descriptor Prototype 

Figure 2-4 shows the descriptor prototype format, which consists of at least 
two longwords. 

Figure 2-4 Descriptor Prototype Format 


CLASS 

DTYPE 

LENGTH 

: Descriptor 

POINTER 
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Symbol 


Description 



DSC$W_LENGTH 

<0J5:0> 

DSC$B_DTYPE 

<0,23:16> 


A 1-word field specific to the descriptor class, 
typically a 16-blt (unsigned) length. 

A 1-byte data type code. Data type codes are 
listed in Sections 2.8.1 and 2.8.2. 
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Symbol 

Description 


DSC$B_CLASS 

<0,31:24> 

A 1 -byte descriptor class code that identifies the 
format and interpretation of the other fields of the 
descriptor as specified in the following sections. 
This Interpretation is intended to be independent 
of the DTYPE field, except for the data types that 
are made up of units that are less than a byte 
(packed-decimal string (P), aligned bit string (V), 
and unaligned bit string (VU)). The CLASS code 
may be used at run time by a called procedure to 
determine which descriptor is being passed. 

DSC$ A-POINTER 
<1,31:0> 

A longword containing the address of the first byte 
of the data element described. 


Note that the descriptor can be placed in a pair of registers with a MOVQ 
instruction and then the length and address can be used directly. This 
gives a word length, so the class and type are placed as bytes in the rest 
of that longword. When the class field is zero, no more than the preceding 
information can be assumed. 


Fixed-Length Descriptor (DSC$K_CLASS_S) 

A single descriptor form is used for scalar data and fixed-length strings. 
Any VAX data type can be used with this descriptor, except data type 
34 (unaligned bit string). Figure 2-5 shows the format of a fixed-length 
descriptor. 

Figure 2-5 Fixed-length Descriptor Format 


1 

DTYPE 

LENGTH 

POINTER 


: Descriptor 
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Symbol 

Description 


DSC$W_LENGTH 

Length of data item in bytes, unless the DSC$B_DTYPE 
field contains the value 1 (aligned bit string) or 21 (packed- 
decimal string). Length of data item is in bits for bit. Length 
of data item is the number of 4-bit digits (not Including the 
sign) for packed-decimal string. 

DSC$B_DTYPE 

A 1-byte data type code. Data 
Sections 2.8.1 and 2.8.2. 

1 type codes are listed in 

DSC$B_CLASS 

1 = DSC$K_CLASS_S. 


DSC$A POINTER 

Address of first byte of data storage. 


If the data type is 14 (character string) and the string must be extended in 
a string comparison or is being copied to a fixed-length string containing a 
greater length, the space character (hexadecimal 20 if ASCII) is used as the fill 
character. 
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2.9.3 Dynamic String Descriptor (DSC$K—CLASS_D) 

A single descriptor form is used for dynamically allocated strings. When 
a string is written, either or both the length field and the pointer field can 
be changed. The VMS Run-Time Library provides procedures for changing 
fields. As an input parameter, this format is interchangeable with class 
1 (DSC$K_CLASS—S). Figure 2-6 shows the format of a dynamic string 
descriptor. 

Figure 2-6 Dynamic String Descriptor Format 


2 

□TYPE 

LENGTH 

POINTER 


: Descriptor 
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Symbol 

Description 


DSC$W_LENGTH 

Length of data item in bytes, unless the DSC$B_DTYPE 
field contains the value 1 (aligned bit string) or 21 (packed- 
decimal string). Length of data item is in bits for bit. Length 
of data item is the number of 4-bit digits (not including the 
sign) for packed-decimal string. 

DSC$B_DTYPE 

A 1-byte data type code. Data type 
Sections 2.8.1 and 2.8.2. 

codes are listed in 

DSC$B_CLASS 

2 = DSC$K_CLASS_D. 


DSC$A_POINTER 

Address of first byte of data storage 



2.9.4 Variable Buffer Descriptor (DSC$K_CLASS_V) 

This descriptor is reserved for use by DIGITAL. 

2.9.5 Array Descriptor (DSC$K_CLASS_A) 

The array descriptor is used to describe contiguous arrays of atomic data 
types or contiguous arrays of fixed-length strings. An array descriptor consists 
of three contiguous blocks. The first block contains the descriptor prototype 
information and is part of every array descriptor. The second and third blocks 
are optional. If the third block is present, so is the second. Figure 2-7 shows 
the format of an array descriptor. 
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Figure 2-7 Array Descriptor Format 


4 

DTYPE 

LENGTH 

POINTER 

DIMCT 

AFLAGS 

DIGITS SCALE 

ARSIZE 


: Descriptor 


Block 1 - Prototype 



Block 2- Multipliers 


Block 3- Bounds 


ZK-1888-84 


Symbol Description 

DSC$W_LENGTH Length of an array element in bytes, unless the 

DSC$B_DTYPE field contains the value 1 (aligned bit string) 
or 21 (packed-decimal string). Length of an array element is 
in bits for bit. Length of an array element is the number of 
4-bit digits (not including the sign) for packed-decimal string. 

DSC$B_DTYPE A 1-byte data type code. Data type codes are listed in 
Sections 2.8.1 and 2.8.2. 


DSC$B_CLASS 

DSC$A_POINTER 

DSC$B_SCALE 

<2,7:0> 

DSC$B_DIGITS 

<2,15:8> 


4 = DSC$K_CLASS_A. 

Address of first actual byte of data storage. 

Signed power-of-two or -ten multiplier, as specified by 

DSC$V_FI_BINSCALE, to convert the internal form to 

external form. (See Section 2.9.10.) 

If nonzero, the unsigned number of decimal digits in the 
internal representation. If zero, the number of digits can be 
computed based on DSC$W_LENGTH. 
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Symbol Description 


DSC$B_AFLAGS 

<2,23:16> 


DSC$B_DIMCT 

<2,31:24> 

DSC$L_ARSIZE 

<3,31:0> 


DSC$A_AO 

<4,31:0> 


Array flag bits: 


Reserved 


Must be zero. 


<2J8:16> 

DSC$V_FL_BINSCALE 

<2J9> 


DSC$V_FL_REDIM 

< 2 , 20 > 


DSC$V_FL .COLUMN 

< 2 , 21 > 


DSC$V_FL_COEFF 

< 2 . 22 > 


DSC$V_FL .BOUNDS 
<2,23> 


If set, the scale factor specified 
by DSC$B.SCALE is a signed 
power-of-two multiplier to convert 
the internal form to external 
form. If not set, DSC$B.SCALE 
specifies a signed power-of-ten 
multiplier. (See Section 2.9.10.) 

If set, the array can be 
redimensioned; that is, 
DSC$A.A0, DSC$L.Mi, 

DSC$I—Li, and DSC$I_Ui may 

be changed. The redimensioned 
array cannot exceed the size 
allocated to the array 
(DSC$L.ARSIZE). 

If set, the elements of the 
array are stored by columns 
(FORTRAN). That Is, the left-most 
subscript (first dimension) is 
varied most rapidly, and the right¬ 
most subscript (nth dimension) 

Is varied least rapidly. If not set, 
the elements are stored by rows 
(most other languages). That is, 
the right-most subscript is varied 
most rapidly and the left-most 
subscript Is varied least rapidly. 

If set, the multiplicative 
coefficients in Block 2 are present. 
Must be set if 
DSC$V.FL.BOUNDS is set. 

If set, the bounds information in 
Block 3 is present and requires 
that DSC$V.FL.COEFF be set. 


Number of dimensions, n. 


Total size of array (in bytes unless the DSC$B.TYPE field 
contains the value 21 ; see the description for 
DSC$W.LENGTH). A redimensioned array may use less than 
the total size allocated. 

For data type 1 (aligned bit string), DSC$W.LENGTH is in 
bits while DSC$I—ARSIZE is In bytes because the unit of 
length Is bits while the unit of allocation is aligned bytes. 

Address of element A(0,0, . . . ,0). This need not be within 
the actual array. It is the same as DSC$A.POINTER for 
zero-origin arrays. 
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Symbol 

Description 

DSC$L_Mi 

Addressing coefficients ( Mi = Ui-Li+1 ). 

<4+i,31:0> 


DSC$L_Li 

Lower bound (signed) of /th dimension. 

<3+n+2»i,31:0> 

DSC$L_Ui 

Upper bound (signed) of /th dimension. 

<4+n+2*i,31:0> 


The following formulas specify the effective address, E, of an array element. 


Warning: Modification of the following formulas is required if DSC$B_DTYPE 
contains a 1 or 21 because DSC$W_LENGTH is given in bits or 4-bit 
digits rather than bytes. 

The effective address, E, for element A(I): 

E = Aq + I+LENGTH 

= POINTER + [I - Li]*LENGTH 

The effective address, E, for element A(Ii,l 2 ) with DSC$V_FL—COLUMN 
clear: 

E = Aq + [Ii*M 2 + l2]*LENGTH 

= POINTER + [[Ii-Li]*M2 + I2 * L2]♦LENGTH 

The effective address, E, for element A(li,l 2 ) with DSC$V_FL—COLUMN set: 

E = Aq + [l2*Mi + Ij]♦LENGTH 

= POINTER + [[l2-L2]^Mi + Ii - Lj]♦LENGTH 

The effective address, E, for element Aflj, . . . ,In) with 
DSC$V-FL-COLUMN clear: 

E = Aq + [[[[... [Ii]^M2 + . • .]^Mj ,_2 Ifi— 2 ^*^n —1 
+ In-il^Mn + In]*LENGTH 

= POINTER + [[[[... [Ii - Li]^M 2 + ...]^Mn_2 + In-2 
- Ln_2]^Mn-l + In-1 ' 

Ln_ 1 ]♦Mn ♦ In ” Lnl♦LENGTH 

The effective address, E, for element Aflj, . . . ,In) with 
DSC$V-FL-COLUMN set: 

E = Aq + [[[[... [Inl^Mn-1 ♦ • • •]^M3 
+ Iq]*M2 l2]^M2 Ij]♦LENGTH 

= POINTER + [[[[...[In " Lnl^Mn-i + ...]^M3 + I3 
- L3]^M2 ♦ I2 ** L23 ♦Mj 
+ Ij - Lj]♦LENGTH 
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2.9.6 Procedure Descriptor {DSC$K_CLASS_P) 

The descriptor for a procedure specifies its entry address and function value 
data type, if any. Figure 2-8 shows the format of a procedure descriptor. 

Figure 2—8 Procedure Descriptor Format 


5 

□TYPE 

LENGTH 

POINTER 


ZK-1893-84 


Symbol 

Description 

DSC$W_LENGTH 

Length associated with the function value, or zero if no 
function value is returned. 

DSC$B_DTYPE 

Function value data type code. Data type codes are listed in 
Sections 2.8.1 and 2.8.2. 

DSC$B_CLASS 

5 = DSK$K_CLASS_P. 

DSC$A_POINTER 

Address of entry mask to routine. 


Procedures return a function value in RO, R1 /RO, or using the first argument 
list entry depending on the size of the data type (see Section 2.4). 


2.9.7 Procedure Incarnation Descriptor (DSC$K_CLASS_PI) 

The procedure incarnation descriptor is obsolete. 

2.9.8 Label Descriptor (DSC$K_CLASS_J) 

The label descriptor is reserved for use by the VMS Debugger. 

2.9.9 Label Incarnation Descriptor (DSC$K_CLASS_JI) 

The label incarnation descriptor is obsolete. 

2.9.10 Decimal String Descriptor (DSC$K_CLASS—SD) 

Figure 2-9 shows the format of a decimal string descriptor. Decimal size and 
scaling information for both scalar data and simple strings is given in this 
descriptor form. 
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Figure 2-9 Decimal String Descriptor Format 


9 

□TYPE 

LENGTH 


POINTER 


RESERVED 

DIGITS 

SCALE 


ZK-1894- 

84 


Symbol 

Description 

DSC$W_LENGTH 

Length of data Item in bytes, unless the DSC$B_DTYPE 
field contains the value 1 (aligned bit string) or 21 (packed- 
decimal string). Length of data item is in bits for bit. Length 
of data Item is the number of 4-blt digits (not Including the 
sign) for packed-decimal string. 

DSC$B_DTYPE 

A 1-byte data type code. Data type codes are listed in 
Sections 2.8.1 and 2.8.2. 

DSC$B_CLASS 

9 = DSC$K_CLASS_SD. 

DSC$ A-POINTER 

Address of first byte of data storage. 

DSC$B_SCALE 

<2,7:0> 

Signed power-of-two or -ten multiplier, as specified by 

DSC$V_FI_BINSCALE, to convert the internal form to 

external form. (See examples in the following table.) 

DSC$B_DIGITS 

<2,15:8> 

If nonzero, the unsigned number of decimal digits in the 
internal representation. If zero, the number of digits can be 
computed based on DSC$W_LENGTH. 

DSC$B_SFLAGS 

<2,23:16> 

Scalar flag bits: 

Reserved Must be zero. 

<2,18:16> 


DSC$V_FI_BINSCALE If set, the scale factor specified 

<2,19> by DSC$B_SCALE is a signed 

power-of-two multiplier to convert 
the internal form to external 
form. If not set, DSC$B_SCALE 
specifies a signed power-of-ten 
multiplier. (See examples in the 
following table.) 

Reserved Must be zero. 

<2,23:20> 


Examples of DSC$B_SCALE and DSC$V_-FL—BINSCALE interpretation are 
presented in the following table: 


Internal 

Value 

DSC$B-SCALE 

DSC$V-FL BINSCALE 

External 

Value 

123 

+1 

0 

1230 

123 

+1 

1 

246 

200 

-2 

0 

2 

200 

-2 

1 

50 
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2.9.11 Noncontiguous Array Descriptor (DSC$K—CLASS_NCA) 

The noncontiguous array descriptor describes an array in which the storage of 
the array elements may be allocated with a fixed, nonzero number of bytes 
separating logically adjacent elements. Two elements are said to be logically 
adjacent if their subscripts differ by 1 in the most rapidly varying dimension 
only. The difference between the addresses of two adjacent elements is 
termed the stride. Whether elements are stored by row or by column is the 
option of the calling program, and is automatically taken care of by a single 
accessing algorithm used by the called procedure. 

This array descriptor is to be used where the calling program, at its option, 
can pass a slice of an array that contains noncontiguous allocations. This 
standard indicates no preference between the noncontiguous array descriptor 
(NCA) and the contiguous array descriptor (A), as described in Section 2.9.5, 
for language processors that always allocate contiguous arrays. 

Figure 2-10 shows the format of a noncontiguous array descriptor, which 
consists of three contiguous blocks. 

Figure 2-10 Noncontiguous Array Descriptor Format 
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Symbol 

DSC$W_LENGTH 


DSC$B_DTYPE 

DSC$B_CLASS 

DSC$A_POINTER 

DSC$B_SCALE 

< 27 : 0 > 

DSC$B_DIGITS 

<2J5:8> 


DSC$B_AFLAGS 

<2,23:16> 


DSC$B_DIMCT 

<2,31:24> 

DSC$L_ARSIZE 

<3,31:0> 


Description ___ 

Length of an array element in bytes, unless the 
DSC$B_DTYPE field contains the value 1 (aligned bit 
string) or 21 (packed-decimal string). Length of an array 
element is in bits for bit. Length of an array element 
is the number of 4-bit digits (not including the sign) for 
packed-decimal string. 

A 1-byte data type code. Data type codes are listed in 
Sections 2.8.1 and 2.8.2. 

10 = DSC$K_CLASS_NCA. 


Address of first actual byte of data storage. 

Signed power-of-two or -ten multiplier, as specified by 

DSC$V_FI_BINSCALE, to convert the internal form to 

external form. (See Section 2.9.10.) 

If nonzero, the unsigned number of decimal digits in the 
internal representation. If zero, the number of digits can 
be computed based on DSC$W_LENGTH. 


Array flag bits: 
Reserved 
<2,18:16> 

DSC$V_FL-BINSCALE 
<2,19> 


DSC$V_FL-REDIM 

< 2 , 20 > 

Reserved 

<2,23:21> 


Reserved for future 
standardization by DIGITAL. 
Must be zero. 

If set, the scale factor specified 
by DSC$B-SCALE Is a signed 
power-of-two multiplier to 
convert the internal form to 
external form. If not set, 
DSC$B-SCALE specifies a 
signed power-of-ten multiplier. 
(See Section 2.9.10.) 

Must be zero. 

Reserved for future 
standardization by DIGITAL. 
Must be zero. 


Number of dimensions, n. 


If the elements are actually contiguous, ARSIZE is the 
total size of the array (In bytes, unless the DSC$B—DTYPE 
field contains the value 21 — see description of 
DSC$W-LENGTH). If the elements are not allocated 
contiguously or if the program unit allocating the 
descriptor is uncertain whether the array is actually 
contiguous, the value placed In ARSIZE may be 
meaningless. 

For data type 1 (aligned bit string), DSC$W—LENGTH is 

In bits while DSC$I_ARSIZE is in bytes because the unit 

of length is in bits while the unit of allocation Is aligned 
bytes. 
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Symbol 

Description 

DSC$A A0 

<4,31:0> 

Address of element A(0,0, . . . ,0). This need not be 
within the actual array. It is the same as 

DSC$A_POINTER for zero-origin arrays. 


DSC$A_A0 = POINTER - ( Si*L, + Sz'Lj + . . . +Sn*Ln) 

DSC$L_Si 

<4+i,31:0> 

Stride of the rth dimension. The difference between the 
addresses of successive elements of the rth dimension. 

DSC$L_Li 

<3+n+2*i,31:0> 

Lower bound (signed) of the rth dimension. 

DSC$L_Ui 

<4+n+2»i,31:0> 

Upper bound (signed) of the rth dimension. 


The following formulas specify the effective address, E, of an array element. 

WARNING: Modification of the following formulas is required if DSC$B_DTYPE 
equals 1 or 21 because DSC$W_LENGTH is given in bits or 4-bit digits 
rather than bytes. 

The effective address, E, of A(I): 

E = Aq + $ 1*1 

= POINTER + Si*[I - Lj] 

The effective address, E, of A(Ii,l 2 ): 

E “ Aq + Sj^Ij + 82*12 

= POINTER + Sj*[Ij - Lj] + 82* [I2 - L2] 

The effective address, E, of A(Ii, . . . 

E = Aq + Si*Ii + . . . + 8n*In 

= POINTER + 8j*[Ij - Lj] + . . . + 8n*[In 
- Lnl 


2.9.12 Varying String Descriptor (DSC$K_CLASS_VS) 

A single descriptor form is used for varying string data types consisting of the 
following two fixed-length areas allocated contiguously with no padding in 
between: 

CURLEN An unsigned word specifying the current length in bytes of the 
immediately following string (byte aligned). 

BODY A fixed-length area containing the string that can vary from zero to a 
maximum length defined for each instance of string. 

As an input parameter, this format is not interchangeable with class 1 
(DSC$K_CLASS_S) or with class 2 (DSC$K_CLASS-.D). When a called 
procedure modifies a varying string passed by reference or by descriptor, it 
writes the new length, n, into CURLEN and may modify all bytes of BODY. 
Figure 2-11 shows the format of a varying string descriptor. 
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Figure 2-11 Varying String Descriptor Format 


11 

DTYPE 

MAXSTRLEN 


POINTER 



ZK-1896-84 


Symbol 

Description 

DSC$W_MAXSTRLEN 

Maximum length of the BODY field of the varying 
string in bytes in the range 0 to 2’®-1. 

DSC$B_DTYPE 

A 1 -byte data type code that must have the value 
37, which specifies the varying character string 
data type (see Sections 2.8.2 and 2.8.7). The 
use of other data types is reserved for future 


standardization. 

DSC$B_CLASS 

11 = DSC$K_CLASS_VS. 

DSC$A_POlNTER 

Address of first field (CURLEN) of the varying 
string. 



In the following example, MAXSTRLEN contains five, CURLEN contains four, 
string is currently ABCD, and the remaining byte is currently undefined. 


31 

0 

11 37 

5 


adr 


15 

0 



4 




A 



B 


c 


D 

\ 

. \ \ 


7 

0 


:descriptor 


:adr 


ZK-1897-84 
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2.9.13 Varying String Array Descriptor (DSC$K_CLASS_VSA) 


CURLEN 

BODY 


A variant of the noncontiguous array descriptor is used to specify an array 
of varying strings where each varying string has the same maximum length. 
Each array element is a varying string data type consisting of the following 
two fixed-length areas allocated contiguously with no padding in between: 

An unsigned word specifying the current length in bytes of the 
immediately following string (byte aligned). 

A fixed-length area containing the string that can vary from zero to 
the maximum length defined for an array element (MAXSTRLEN). 

When a called procedure modifies a varying string in an array of varying 
strings passed to it by reference or by descriptor, it writes the new length, 

«, into CURLEN and may modify all bytes of BODY. The format of this 
descriptor is the same as the noncontiguous array descriptor except for the 
first two longwords. Figure 2-12 shows the format of a varying string arrav 
descriptor. » z 
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Figure 2-12 Varying String Array Descriptor Format 


35 


12 

□TYPE 

MAXSTRLEN 


POINTER 


DIMCT 

AFLAGS 

DIGITS 

SCALE 


ARSIZE 



Block 1 - Prototype 



Block 2 - Strides 


LI 


Block 3 - Bounds 

U1 


• • • 


Ln 


Un 




ZK-1898-84 



Symbol Description 


DSC$W_MAXSTRLEN Maximum length of 

the BODY field of an array 


element in bytes in the range 0 to 2’®-1. 
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Symbol 

Description 

DSC$B_DTYPE 

A 1-byte data type code that must have the value 
37, which specifies the varying character string 
data type (see Sections 2.8.2 and 2.8.7). The 
use of other data types is reserved for future 
standardization. 

DSC$B_CLASS 

12 = DSC$K_CLASS_VSA. 

DSC$A_POINTER 

Address of first actual byte of data storage. 


The remaining fields in the descriptor are identical to those in the 
noncontiguous array descriptor (NCA). The effective address computation 
of an array element produces the address of CURLEN of the desired element. 


2.9.14 Unaligned Bit String Descriptor (DSC$K_CLASS_UBS) 

A descriptor is used to pass an unaligned bit string (DSC$K_DTYPE_VU) 
that starts on an arbitrary bit boundary and ends on an arbitrary bit boundary. 
The length is 0 to 2^^-l bits. The bit string may be accessed directly using 
the VAX variable bit field instructions. Therefore, the descriptor provides two 
components: a base address and a signed relative bit position. Figure 2-13 
shows the format of an unaligned bit string descriptor. 

Figure 2—13 Unaligned Bit String Descriptor Format 


13 


DTYPE 


LENGTH 


BASE 

POS 


: Descriptor 


ZK-1899-84 


Symbol 

Description 

DSC$W_LENGTH 

Length of data Item in bits. 

DSC$B_DTYPE 

A 1-byte data type code that has the value 34, which 
specifies the unaligned bit string data type (see Sections 
2.8.1 and 2.8.2). The use of other data types is reserved 
for future standardization. 

DSC$B_CLASS 

13 = DSC$K_CLASS_UBS 

DSC$A_BASE 

Base of address relative to which the signed relative bit 
position, POS, is used to locate the bit string. The base 
address need not be first actual byte of data storage. 

DSC$L_POS 

Signed longword relative bit position with respect to BASE 
of the first bit of unaligned bit string. 
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2.9.1 






5 


For example, a called procedure can use the following instruction to access a 
bit string of 32 bits or less: 

EXTZV DSC$L_P0S(R0), DSC$W_LENGTH(RO). aDSC$A_BASE(RO), R1 

If RO contains the address of the descriptor, this instruction copies the bit 
string to Rl. 

Unaligned Bit Array Descriptor {DSC$K_CLASS_UBA) 

A variant of the noncontiguous array descriptor is used to specify an array 
of unaligned bit strings. Each array element is an unaligned bit string data 
type (DSC$K_DTYPE_VU) that starts on an arbitrary bit boundary and ends 
on an arbitrary bit boundary. The length of each element is the same and 
is 0 to 2^^-l bits. You can access elements of the array directly, using the 
VAX variable bit field instructions. Therefore, the descriptor provides two 
components: a byte address, DSC$A_BASE, and a means to compute the 
signed bit offset, EB, with respect to BASE of an array element. 

The unaligned bit array descriptor consists of four contiguous blocks that are 
always present. The first block contains the descriptor prototype information. 
Figure 2-14 shows the format of an unaligned bit array descriptor. 
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Figure 2—14 Unaligned Bit Array Descriptor Format 


14 

□TYPE 

LENGTH 

BASE 

DIMCT 

AFLAGS 

DIGITS 

SCALE 

ARSIZE 




.'Descriptor 


Block 1 - Prototype 


Block 2- Strides 



Block 3-Bounds 


POS 


Block 4 - Position 

ZK-1900- 


84 
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Symbol 

DSC$W_LENGTH 

DSC$B_DTYPE 


DSC$B_CLASS 

DSC$A_BASE 

DSC$B_SCALE 

DSC$B_DIGITS 

DSC$B_AFLAGS 

<2,23:16> 


DSC$B_DIMCT 

<2,31:24> 

DSC$L_ARS1ZE 

<3,31:0> 


DSC$L_VO 

<4,31.0> 

DSC$L_Si 

<4+i,31:0> 


DSC$L_Li 
<3+n+2*i,31:0> 

DSC$L_Ui 

<4+n+2«i,31:0> 

DSC$L_POS 

<5+n<>3,31:0> 


Description 

Length of an array element in bits. 

A 1-byte data type code that must have the value 34, 
which specifies the unaligned bit string data type (see 
Sections 2.8.1 and 2.8.2). The use of other data types is 
reserved for future standardization. 


14 = DSC$K_CLASS_UBA. 

Base address relative to the effective bit offset, EB, used 
to locate elements of the array. The base address need 
not be the first actual byte of data storage. 

Reserved for future standardization by DIGITAL. Must be 
zero. 


Reserved for future standardization by DIGIT AL. Must be 


zero. 

Array flag bits: 

Reserved 

<2,18:16> 

DSC$V_FL_BINSCALE 

<2,19> 

DSC$V_FL_REDIM 

< 2 , 20 > 

Reserved 
<2,23:21 > 

Number of dimensions, n. 


Reserved for future 
standardization by DIGITAL. 
Must be zero. 

Must be zero. 

Must be zero. 

Reserved for future 
standardization by DIGITAL. 
Must be zero. 


If the elements are actually contiguous, ARSIZE is 
the total size of the array in bits. If the elements 
are not allocated contiguously or if the program unit 
allocating the descriptor is uncertain whether the array is 
actually contiguous, the value placed in ARSIZE may be 
meaningless. 

Signed bit offset of element A(0, ... ,0) with respect to 
BASE. Vo = POS - [Si«Li + . . . + Sn'Ln]. 

Stride of the /th dimension. The difference between the 
bit (not byte) addresses of successive elements of the rth 
dimension. 

Lower bound (signed) of the fth dimension. 

Upper bound (signed) of the rth dimension. 

Signed longword relative bit position with respect to 
BASE of the first actual bit of the array, that is, element 
A(Li.U). 






VAX Procedure Calling and Condition Handling Standard 


The signed, 32-bit effective bit offset,'EB, of Aflj): 

EB = Vq + Sj*Ij 

= POS + Si*[Ii - Lj] 

The signed, 32-bit effective bit offset, EB, of A(Ii,l 2 ): 

EB = Vq + S|*I| + $2*12 

= POS + Si*[Ii - Lj] + S2*[l2 - L 2 ] 

The signed, 32-bit effective bit offset, EB, of A(Ii, . . . , !„): 

EB = Vq + Si*Ii + . . . + Sn*In 

= POS + Si*[Ii - Lj] + ... + Sn*[In 
■ Ln] 

Note that EB is computed ignoring integer overflow. EB is then usable as the 
position operand, and the contents of DSC$A_BASE is usable as the base 
address operand in the VAX variable-length bit field instructions. Therefore, 

BASE must specify a byte that is within 2^8 bytes of all bytes of storage in 
the bit array. 

For example, consider a 1-origin, 1-dimension, 5-element array consisting of 
3-bit elements allocated adjacently (therefore, SI = 3). Assume BASE is byte 
1000 and the first actual element, A(l), starts at bit <4> of byte 1001. 


:1000 


1001 


1002 


1003 


ZK-1901-84 

The following dependent field values occur in the descriptor: 
POS = 12 

Vq = 12 - 3*1 = 9 


2.9.16 String with Bounds Descriptor (DSC$K_CLASS_SB) 

A variant of the fixed-length string descriptor is used to specify strings where 
the string is viewed as a one-dimensional array with user-specified bounds. 
Figure 2-15 shows the format of a string with bounds descriptor. 
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Figure 2-15 String with Bounds Descriptor Format 


15 


□TYPE 


LENGTH 


POINTER 


SB_L1 


SB_U1 


:Descriptor 


ZK-1908-84 


Symbol 


Description 


DSC$W_LENGTH 

DSC$B_DTYPE 


DSC$B_CLASS 
DSC$ A-POINTER 
DSC$L_SB_L1 
DSC$L SB U1 


Length of string in bytes. 

A 1-byte data type code that must have the value 14, 
which specifies the character string data type (see Sections 
2.8.1 and 2.8.2). The use of other data types is reserved 
for future standardization. 

15 = DSC$K_CLASS_SB. 

Address of first byte of data storage. 

Lower bound (signed) of the first (and only) dimension. 
Upper bound (signed) of the first (and only) dimension. 


The following formula specifies the effective address, E, of a string element 
A(l): 


E = POINTER + [I - SB_L1] 


2.9.1 



7 


If the string must be extended in a string comparison or assignment, the space 
character (hexadecimal 20 if ASCII) is used as the fill character. 


Unaligned Bit String with Bounds Descriptor {DSC$K_CLASS_UBSB) 

A variant of the unaligned bit string descriptor is used to specify bit strings 
where the string is viewed as a one-dimensional bit array with user-specified 
bounds. Figure 2-16 shows the format of an unaligned bit string with bounds 
descriptor. 
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Figure 2-16 Unaligned Bit String with Bounds Descriptor Format 
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Symbol 

Description 

DSC$W_LENGTH 

Length of data item in bits. 

DSC$B_DTYPE 

A 1-byte data type code that must have the value 34, 
which specifies the unaligned bit string data type (see 
Sections 2.8.1 and 2.8.2.) The use of other data types is 
reserved for future standardization. 

DSC$B_CLASS 

16 = DSC$K_CLASS_UBSB. 

DSC$A_BASE 

Base address relative to the signed relative bit position, 
POS, used to locate the bit string. The base address need 
not be the first actual byte of data storage. 

DSC$L_POS 

Signed longword relative bit position with respect to 

BASE of the first bit of the unaligned bit string. 

DSC$L_UBSB_L1 

Lower bound (signed) of the first (and only) dimension. 

DSC$L UBSB U1 

Upper bound (signed) of the first (and only) dimension. 


The following formula specifies the effective bit offset, EB, of a bit element 
A(I): 


EB = POS + [I - UBSB.Ll] 
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2.9.18 Facility-Specific Descriptor Class Codes 

Descriptor class codes 160 through 191 are reserved by DIGITAL for facility- 
specific purposes. These codes must not be passed between facilities because 
different facilities may use the same code for different purposes. These codes 
may be used by compiler-generated code to pass parameters to the language- 
specific, run-time support procedures associated with that language or to VAX 
DEBUG. 


2.9.19 Reserved Descriptor Class Codes 

Descriptor classes 15 through 191 are reserved by DIGITAL. Classes 192 
through 255 are reserved for DIGITAL's Computer Special Systems group and 
customers. 


2.10 VAX Conditions 

A condition is either (1) a hardware-generated synchronous exception or (2) 
a software event that is to be processed in a manner analogous to a hardware 
exception. 

Floating-point overflow exception, memory access violation exception, and 
reserved operation exception are examples of hardware-generated conditions. 
An output conversion error, an end of file, or the filling of an output buffer 
are examples of software events that might be treated as conditions. 

Depending on the condition and on the program, you can take four types of 
action when a condition occurs; 

• Ignore the condition. 

For example, if an underflow occurs in a floating-point operation, 
continuing from the point of the exception with a zero result may be 
satisfactory. 

• Take some special action and then continue from the point at which the 
condition occurred. 

For example, if the end of a buffer is reached while a series of data items 
are being written, the special action is to start a new buffer. 
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• End the operation and branch from the sequential flow of control. 

For example, if the end of an input file is reached, the branch exits from a 
loop that is processing the input data. 

• Treat the condition as an unrecoverable error. 

For example, when the floating divide-by-zero exception condition occurs, 
the program exits after writing (optionally) an appropriate error message. 

When an unusual event or error occurs in a called procedure, the procedure 
can return a condition value to the caller indicating what has happened (see 
Section 2.5). The caller tests the condition value and takes the appropriate 
action. 

When an exception is generated by the hardware, a branch out of the 
program's flow of control occurs automatically. In this case, and for certain 
software-generated events, it is more convenient to handle the condition as 
soon as it is detected rather than to program explicit tests. 


2.10.1 Condition Handlers 

To handle hardware- or software-detected exceptions, the' VAX Condition 
Handling Facility allows you to specify a condition handler procedure to be 
called when an exception condition occurs. 

An active procedure can establish a condition handler to be associated with it. 
The presence of a condition handler is indicated by a nonzero address in the 
first longword of the procedure's stack frame. When an event occurs that is 
to be treated using the condition-handling facility, the procedure detecting the 
event signals the event by calling the facility and passing a condition value 
describing the condition that occurred. This condition value has the format 
and interpretation as described in Section 2.5. All hardware exceptions are 
signaled. 

When a condition is signaled, the condition-handling facility looks for a 
condition handler in the current procedure's stack frame. If a handler is 
found, it is entered. If no handler is associated with the current procedure, 
the immediately preceding stack frame is examined. Again, if a handler is 
found, it is entered. If a handler is not found, the search of previous stack 
frames continues until the default condition handler established by the system 
is reached or the stack runs out. 

The default condition handler prints messages indicated by the signal 
argument list by calling the Put Message (SYS$PUTMSG) system service, 
followed by an optional symbolic stack traceback. Success conditions with 
STS$K_SUCCESS result in messages to SYS$OUTPUT only. All other 
conditions, including informational messages (STS$K_INFO), produce 
messages on SYS$OUTPUT and SYS$ERROR. 

For example, if a procedure needs to keep track of the occurrence of the 
floating-point underflow exception, it can establish a condition handler to 
examine the condition value passed when the handler is invoked. Then, 
when the floating-point underflow exception occurs, the condition handler 
is entered and logs the condition. The handler returns to the instruction 
immediately following the instruction causing the underflow. 
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If floating-point operations occur in many procedures of a program, the 
condition handler can be associated with the program's main procedure. 
When the condition is signaled, successive stack frames are searched until 
the stack frame for the main procedure is found, at which time the handler 
is entered. If a user program has not associated a condition handler with any 
of the procedures that are active at the time of the signal, successive stack 
frames are searched until the frame for the system program invoking the user 
program is reached. A default condition handler that prints an error message 
is then entered. 


2.10.2 Condition Handler Options 

Each procedure activation potentially has a single condition handler 
associated with it. This condition handler is entered whenever any condition 
is signaled within that procedure. (It can also be entered as a result of signals 
within active procedures called by the procedure.) Each signal includes a 
condition value (see Section 2.5) that describes the condition causing the 
signal. When the condition handler is entered, the condition value should be 
examined to determine the cause of the signal. After the handler processes 
the condition or ignores it, it can take one of the following actions: 

• Return to the instruction immediately following the signal. Note that it is 
not always possible to make such a return. 

• Resignal the same or a modified condition value. A new search for a 
condition handler begins with the immediately preceding stack frame. 

• Signal a different condition. 

• Unwind the stack. 


2.11 Operations Involving Condition Handlers 

The VAX Condition Handling Facility provides functions to perform the 
following operations: 

• Establish a condition handler. 

A condition handler is associated with the current pocedure by placing 
the handler's address in the current procedure's activation stack frame. 

• Revert to the caller's handling. 

If a condition handler has been established, you can remove it by clearing 
its address in the current procedure activation's stack frame. 

• Enable or disable certain arithmetic exceptions. 

The software can enable or disable the following hardware exceptions: 
floating-point underflow, integer overflow, and decimal overflow. No 
signal occurs when the exception is disabled. 

• Signal a condition. 

Signaling a condition initiates the search for an established condition 
handler. 
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• Unwind the stack. 

Upon exit from a condition handler it is possible to remove one or more 
frames occurring before the signal from the stack. During the unwinding 
operation, the stack is scanned; if a condition handler is associated with 
a frame, that handler is entered before the frame is removed. Unwinding 
the stack allows a procedure to perform application-specific cleanup 
operations before exiting. 


2.11.1 Establishing a Condition Handler 

Each procedure activation has a condition handler potentially associated 
with it, using longword 0 in its stack frame. Initially, longword 0 contains 
the value 0, indicating no handler. You establish a handler by moving the 
address of the handler's procedure entry point mask to the establisher's stack 
frame. 

In addition, the VMS operating system provides three statically allocated 
exception vectors for each access mode of a process. These vectors are 
available to declare condition handlers that take precedence over any handlers 
declared at the procedure level. These are used, for example, to allow a 
debugger to monitor all exceptions and for the system to establish a last- 
chance handler. Because these handlers do not obey the procedure-nesting 
rules, they should not be used by modular code. Instead, the stack-based 
declaration should be used. 

The following code establishes a condition handler: 

MOVAB handler_entry_point,0(FP) 


2.11.2 Reverting to the Caller's Handling 

Reverting to the caller's handling deletes the condition handler associated 
with the current procedure activation. You do this by clearing the handler 
address in the stack frame. 

The code to revert to the caller's handling is as follows: 

CLRL 0(FP) 


2.11.3 Signaling a Condition 

The signal operation is the method used for indicating the occurrence of an 
exception condition. To issue a message and be able to continue execution 
after handling the condition, a program calls the LIB$SIGNAL procedure, as 
follows: 

CALL LIB$SIGNAL (condition-value, arg_list...) 

To issue a message, but not continue execution, a program calls LIB$STOP, as 
follows: 

CALL LIB$ST0P (condition-value, arg_list...) 


2—44 








VAX Procedure Calling and Condition Handling Standard 


In both cases, the condition-value argument indicates the condition that 
is signaled. However, LIB$STOP sets the severity of the condition-value 
argument to be a severe error. The remaining arguments describe the details 
of the exception. These are the same arguments used to issue a system 
message. 

Note that, unlike most calls, LIB$SIGNAL and LIB$STOP preserve RO and 
R1 as well as the other registers. Therefore, a debugger can insert a call 
to LIB$SIGNAL to display the entire state of the process at the time of 
the exception. It also allows signals to be coded in VAX MACRO without 
changing the register usage. This feature of preserving RO and R1 is useful 
for debugging checks and gathering statistics. Hardware and system service 
exceptions behave like calls to LIB$SIGNAL. 

The signal procedure examines the two exception vectors first, then up to 
64K previous stack frames, and finally the last-chance exception vector, if 
necessary. The current and previous stack frames are found by using FP and 
chaining back through the stack frames using the saved FP in each frame. 

The exception vectors have three address locations per access mode. 

As part of image startup, the system declares a default last-chance handler. 
This handler is used as a last resort when the normal handlers are not 
performing correctly. The debugger can replace the default system last-chance 
handler with its own. 

In some frame before the call to the main program, the system establishes 
a default catch-all condition handler that issues system messages. In a 
subsequent frame before the call to the main program, the system usually 
establishes a traceback handler. These system-supplied condition handlers 
use the condition-value argument to get the message and then use the 
remainder of the argument list to format and output the message through the 
system service, SYS$PUTMSG. 

If the severity field of the condition-value argument (bits <2:0> ) does not 
indicate a severe error (that is, a value of 4), these default condition handlers 
return with SS$_CONTINUE. If the severity is a severe error, these default 
handlers exit the program image with the condition value as the final image 
status. 

The stack search ends when the old FP is 0 or is not accessible, or when 64K 
frames have been examined. If no condition handler is found, or all handlers 
returned with a SS$_RESIGNAL, then the vectored last-chance handler is 
called. 

If a handler returns SS$_CONTINUE, and LIB$STOP was not called, control 
returns to the signaler. Otherwise, LIB$STOP issues a message indicating that 
an attempt was made to continue from a noncontinuable exception and exits 
with the condition value as the final image status. 

Table 2-4 lists all combinations of interaction between condition handler 
actions, the default condition handlers, the types of signal, and the call to 
signal or stop. In the table, "cannot continue" indicates an error that results in 
the following message; 

IMPROPERLY HANDLED CONDITION. ATTEMPT TO CONTINUE FROM STOP. 
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Table 2—4 Interaction Between Handlers and Default Handlers 


Call to: 

Signaled 

Condition 

Severity 

<2:0> 

Default 

Handler 

Gets Control 

Handler 

Specifies 

Continue 

Handler 

Specifies 

UNWIND 

No Handler 

Is Found 
(stack bad) 

LIB$SICNAL 

or 

hardware 

exception 

<4 

condition 

message 

RET 

RET 

UNWIND 

Call 

last 

chance 

handler 

EXIT 

= 4 

condition 

message 

EXIT 

RET 

UNWIND 

Call 

last 

chance 

handler 

EXIT 

LIBSSTOP 

force 

(=4) 

condition 

message 

EXIT 

"cannot 

continue" 

EXIT 

UNWIND 

Call 

last 

chance 

handler 

EXIT 
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2 Properties of Condition Handlers 

The following subsections describe the properties of condition handlers. 


2.1 Condition Handler Parameters and Invocation 

If a condition handler is found on a software-detected exception, the handler 
is called with the following argument list: 

continue = handler (signal.args, mechanism.args) 

Each argument is a reference to a longword vector. The first longword of 
each vector is the number of remaining longwords in the vector. You can use 
the symbols CHF$L_SIGARGLST (=4) and CHF$L_MCHARGLST (=8) to 
access the condition handler arguments relative to AP. 

The signal _args longword is the condition argument list from the call to 
LIB$SIGNAL or LIB$STOP, expanded to include the PC and PSL of the next 
instruction to execute on a continue. The second longword is the condition 
value being signaled. 
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Because bits <2:0> of the condition value indicate severity and do not 
indicate which condition is being signaled, the handler should examine only 
the condition identification, that is, condition value bits <27:3> . The 
setting of bits <2:0> varies depending upon the environment. In fact, 
some handlers may only change the severity of a condition and resignal. The 
symbols CHF$L_S1G_ARGS (=0) and CHF$L_S1G_NAME (=4) can be 
used to refer to the elements of the signal vectors. 

Figure 2-17 shows the format of the mechanism argument vector. 

Figure 2-17 Format of the Mechanism Argument Vector 


CHF$LMCH_ARGS 

CHF$L_MCH_FRAME 

CHF$L_MCH_DEPTH 

CHF$1_MCH_SAVR0 

CHF$LMCH_SAVR1 
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The frame is the contents of the FP in the establisher's context. If the 
restrictions described in Section 2.12.2 are met, the frame can be used as 
a base to access the local storage of the establisher. 

The depth is a positive count of the number of procedure activation stack 
frames between the frame in which the exception occurred and the frame 
depth that established the handler being called* Depth has the value 0 for 
an exception handled by the procedure activation invoking the exception 
(that is, containing the instruction causing the hardware exception or calling 
L1B$S1GNAL). Depth has positive values for procedure activations calling the 
one having the exception, for example, 1 for the immediate caller. 

If a system service gives an exception, the immediate caller of the service 
is notified at depth = 1 . Depth has value -2 when the condition handler is 
established by the primary exception vector, -I when it is established by the 
secondary vector, and -3 when it is established by the last-chance vector. 

The contents of RO and R1 are the same as at the time of the call to 
L1B$S1GNAL or L1B$ST0P. 

For hardware-detected exceptions, the condition value indicates which 
exception vector was taken; the next 0 or several longwords are additional 
parameters. The remaining two longwords are the PC and PSL. Figure 2-18 
shows the format of the signal argument vector. 
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Figure 2—18 Format of the Signal Argument Vector 
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If one of the default condition handlers established by the system is entered, 
it calls the system service, SYS$PUTMSG, to interpret the signal argument list 
and output the indicated information or error message. See the description of 
SYS$PUTMSG in the VMS System Services Reference Manual for the format of 
the signal argument list. 


2.12.2 Use of Memory 


A condition handler and the procedures it calls can refer only to explicitly 
passed arguments. Handlers cannot refer to COMMON or other external 
storage, and they cannot reference local storage in the procedure that 
established the handler. The existence of handlers does not affect compiler 
optimization. Compilers that do not follow this rule must ensure that any 
variables referred to by the handler are always in memory. 


2.12.3 Returning from a Condition Handler 

Condition handlers are invoked by the VAX Condition Handling Facility. 
Therefore, the return from the condition handler is to the condition-handling 
facility. 

To continue from the instruction following the signal, the handler must return 
with the function value SS$_CONTINUE (true), that is, with bit <0> set. 
If, however, the condition is signaled with a call to LIB$STOP, the image 
exits. To resignal the condition, the condition handler returns with the 
function value SS$_RESIGNAL (false), that is, with bit <0> clear. To alter 
the severity of the signal, the handler modifies the low-order three bits of 
the condition value longword in the signal-args vector and resignals. If the 
condition handler wants to alter the defined control bits of the signal, the 
handler modifies bits <31:28> of the condition value and resignals. To 
unwind, the handler calls SYS$UNW1ND and then returns. In this case, the 
handler function value is ignored. 
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2.12.4 Request to Unwind 

To unwind, the handler or any procedure it calls can make the following call: 

success = SYSSUNWIND 

( [depadr = handler depth + 1], 

[new_PC = return PC ] ) 

The argument depadr specifies the address of the longword containing the 
number of presignal frames (depth) to be removed. If that number is less 
than or equal to 0, then nothing is to be unwound. The default (address=0) 
is to return to the caller of the procedure that established the handler that 
issued the $UNWIND service. To unwind to the establisher, the depth from 
the call to the handler should be specified. When the handler is at depth 0, 
it can achieve the equivalent of an unwind operation to an arbitrary place in 
its establisher by altering the PC in its signal-args vector and returning with 
SS$_CONTINUE instead of performing an unwind. 

The argument new_PC specifies the location to receive control when the 
unwinding operation is complete. The default is to continue at the instruction 
following the call to the last procedure activation removed from the stack. 

The function value SUCCESS is either a standard success code 
(SS$-JSfORMAL), or it indicates failure with one of the following return status 
condition values: 

• No signal active (SS$_NOSIGNAL) 

• Already unwinding (SS$_UNWINDING) 

• Insufficient frames for depth (SS$_INSFRAME) 

The unwinding operation occurs when the handler returns to the condition¬ 
handling facility. Unwinding is done by scanning back through the stack 
and calling each handler that has been associated with a frame. The handler 
is called with exception SS$_UNWIND to perform any application-specific 
cleanup. If the depth specified includes unwinding the establisher's frame, 
the current handler is recalled with this unwind exception. 

The call to the handler takes the same form as previously described, with the 
following values: 

signal_args 

1 

condition_value = SS$_UNWIND 

mechanism_args 

4 

frame establisher’s frame 
depth 0 (that is, unwinding self) 

RO RO that unwind will restore 

R1 R1 that unwind will restore 

After each handler is called, the stack is cut back to the previous frame. 

Note that the exception vectors are not checked because they are not being 
removed. Any function value from the handler is ignored. To specify the 
value of the top-level function being unwound, the handler should modify RO 
and R1 in the mechanism _args vector. They are restored from the 
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mechanism_args vector at the end of the unwind. Depending on the 
arguments to SYS$UNWIND, the unwinding operation is terminated as 
follows: 

SYS$UNWIND(0,0) Unwind to the establisher's caller with 

the establisher function value restored 
from RO and R1 In the mechanism-args 
vector. 

SYS$UNWIND(depth,0) Unwind to the establisher at the point 

of the call that resulted In the exception. 
The contents of RO and R1 are restored 
from RO and R1 in the mechanism—args 
vector. 

SYS$UNWIND(depthJocation) Unwind to the specified procedure 

activation and transfer to a specified 
location with the contents of RO and R1 
from RO and R1 In the mechanism—args 
vector. 

You can call SYS$UNWIND whether the condition was a software exception 
signaled by calling LIB$SIGNAL or LIB$STOP, or was a hardware exception. 
Calling SYS$UNWIND is the only way to continue execution after a call to 
LIB$STOP. 


2.12.5 Signaler's Registers 

Because the handler is called and can in turn call routines, the actual register 
values in use at the time of the signal or exception can be scattered on the 
stack. To find the registers R2 through FP, a scan of stack frames must be 
performed starting with the current frame and ending with the call to the 
handler. During the scan, the last frame found to save a register contains that 
register's contents at the time of the exception. If no frame saved the register, 
the register is still active in the current procedure. The frame of the call to the 
handler can be identified by the return address of SYS$CALL_HANDL+4. 
Thus, the registers are as follows: 


RO, R1 

In mechanism—args 

R2..R11 

Last frame saving It 

AP 

Old AP of SYS$CALL_HANDL+4 frame 

FP 

Old FP of SYS$CALL_HANDL+4 frame 

SP 

Equal to end of signal-args vector-i-4 

PC, PSL 

At end of signal-args vector 
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2.13 Multiple Active Signals 

A signal is said to be active until the signaler gets control again or is 
unwound. A signal can occur while a condition handler or a procedure 
it has called is executing in response to a previous signal. For example, 
procedures A, B, and C establish condition handlers Ah, Bh, and Ch. If A 
calls B and B calls C, which signals S, and Ch resignals, then Bh gets control. 
If Bh calls procedure X, and X calls procedure Y, and Y signals T, the stack is 
as follows: 

<signal T> 

Y 

X 

Bh 

<signal S> 

C 

B 

A 

which was programmed: 

A 


B-►Bh 

C X 

<signal S> Y 

<signal T> 

ZK-1884-84 

The handlers are searched for in the following order: Yh, Xh, Bhh, Ah. Note 
that Ch is not called because it is a structural descendant of B. Bh is not 
called again because that would require it to be recursive. Recursive handlers 
cannot be coded in nonrecursive languages such as FORTRAN. Instead, Bh 
can establish itself or another procedure as its handler (Bhh). 

The following algorithm is used on the second and subsequent signals that 
occur before the handler for the original signal returns to the condition¬ 
handling facility. The primary and secondary exception vectors are checked. 
Then, however, the search backward in the process stack is modified. In 
effect, the stack frames traversed in the first search are skipped over in the 
second search. Thus, the stack frame preceding the first condition handler, up 
to and including the frame of the procedure that has established the handler, 
is skipped. Despite this skipping, depth is not incremented. For example, the 
stack frames traversed in the first and second search are skipped over in a 
third search. Note that if a condition handler signals, it is not automatically 
invoked recursively. However, if a handler itself establishes a handler, this 
second handler will be invoked. Thus, a recursive condition handler should 
start by establishing itself. Any procedures invoked by the handler are 
treated in the normal way; that is, exception signaling follows the stack up to 
the condition handler. 

If an unwinding operation is requested while multiple signals are active, all 
the intermediate handlers are called for the operation. For example, in the 
preceding diagram, if Ah specifies unwinding to A, the following handlers are 
called for the unwind: Yh, Xh, Bhh, Ch, and Bh. 
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For proper hierarchical operation, an exception that occurs during execution 
of a condition handler established in an exception vector should be handled 
by that handler rather than propagating up the activation stack. To prevent 
such propagation, the vectored condition handler should establish a handler 
in its stack frame to handle all exceptions. 
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VMS Data Types 

The VMS Usage entry in the documentation format for system routines 
indicates the VMS data type of the argument. Each VMS data type has only 
one storage representation. For example, the VMS data type access_mode 
is an unsigned byte. In addition, a VMS data type may or may not have a 
conceptual meaning. 

Most VMS data types may be considered conceptual types; that is, they carry 
meaning unique in the context of the VMS operating system. The 
access_mode is one of these. The storage representation of this VMS type is 
an unsigned byte, and the conceptual content of this unsigned byte is the fact 
that it designates a hardware access mode and therefore has only four valid 
values: 0, designating kernel mode; I, executive mode; 2, supervisor mode; 
and 3, user mode. However, some VMS data types are not conceptual types; 
that is, they specify a storage representation, but carry no other semantic 
content from the point of view of VMS. For example, the VMS data type 
byte.^igned is not a conceptual type. 

Note: The VMS Usage entry is NOT a traditional data type such as the VAX 
standard data types—byte, word, longword, and so on. It is significant 
only within the VMS operating system environment and is intended 
solely to expedite data declarations within application programs. 

To use the VMS Usage entry, perform the following procedure: 

1 Find the data type in Table A-1 and read its definition. 

2 Find the same VMS data type in the appropriate VAX language 
implementation table (Tables A-2 through A-13) and its corresponding 
source language type declaration. 

3 Use this code as your type declaration in your application program. Note 
that, in some instances, you may have to modify the declaration. 

Table A-1 lists and describes the VMS data types. 

Table A-1 VMS Data Types 

Data Type Definition 

access_bit_names Homogeneous array of 32 quadword 

descriptors; each descriptor defines the name 
of one of the 32 bits in an access mask. The 
first descriptor names bit <0> , the second 
descriptor names bit < 1 > , and so on. 

access_mode Unsigned byte denoting a hardware access 

mode. This unsigned byte can take four 
values: 0 specifies kernel mode; 1 , executive 
mode; 2 , supervisor mode; and 3 , user mode. 
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Table A-1 (Cont.) 

Data Type 

address 


address_range 


arg_list 


VMS Data Types 

Definition 

Unsigned longword denoting the virtual 
memory address of either data or code, 
but not of a procedure entry mask (which is of 
type procedure). 

Unsigned quadword denoting a range of virtual 
addresses, which identify an area of memory. 
The first longword specifies the beginning 
address in the range; the second longword 
specifies the ending address in the range. 

Procedure argument list consisting of 1 to 
256 longwords. The first longword contains 
an unsigned integer count of the number 
of successive, contiguous longwords, each 
of which is an argument to be passed 
to a procedure by means of a VAX CALL 
instruction. 

The argument list has the following format: 



ast_procedure 


boolean 


byte_slgned 

byte_unslgned 

channel 


Unsigned longword Integer denoting the entry 
mask to a procedure to be called at AST level. 
(Procedures that are not to be called at AST 
level are of type procedure.) 

Unsigned longword denoting a Boolean truth 
value flag. This longword can have only two 
values: 1 (true) and 0 (false). 

Is the same as the data type byte integer 
(signed) in Table 1-3. 

Is the same as the data type byte (unsigned) 
in Table 1-3. 

Unsigned word Integer that is an index to an 
I/O channel. 
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VMS Data Types 

A,1 VMS Data Types 

Table A-1 (Cent.) 

VMS Data Types 



Data Type 


Definition 


char_string 

String of from 0 to 65,535 8-bit characters. 
This VMS data type is the same as the data 
type character string in Table 1-3. The 
following diagram shows the character string 
XYZ: 

7 0 



“X” 


: A 



“Y" 


: A+1 



“Z” 


: A-h2 

complex_number 

ZK-4202-85 

One of the VAX standard complex floating¬ 
point data types. The three complex floating¬ 
point numbers are F_floating complex, 
□-floating complex, and G_floatlng complex. 


An F_floating complex number (rj) is 
comprised of two F_floating point numbers: 
the first is the real part (r) of the complex 
number; the second Is the Imaginary part (i). 
The structure of an F_floating complex number 
is as follows; 

my_^tree 


1st (STRING) '1010' '111' 


2nd (INTEGER) -1 2 10 0 1000 


3rd (STRING) 

'a' 

■b' 

'C. 

■d' 

'x' 

'x' 'y' 

values 

(0) 

(11) 

(5) 

(-5) 

(44) 

(22) (6) 

ZK-4293-85 
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VMS Data Types 

A.1 VMS Data Types 


Table A-1 (Cent.) VMS Data Types 

Data Type Definition 

A D_floating complex number (rj) is 
comprised of two D_floating point numbers: 
the first is the real part (r) of the complex 
number; the second is the imaginary part (i). 
The structure of a D_floating complex number 
Is as follows: 

15 14 43 0 

: A 

: A+2 
: A+4 
: Ah-6 
: A8 
: A+10 
: A+12 
: A+14 

ZK-4200-85 


REAL 

PART 


IMAGINARY 

PART 


EXPONENT 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


EXPONENT 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


A G_floatlng complex number (rj) is 
comprised of two G_floating point numbers: 
the first Is the real part (r) of the complex 
number; the second is the Imaginary part (i). 
The structure of a G_floating complex number 
is as follows: 

15 14 7 6 0 

: A 

: A+2 
: A+4 
: A+6 
: A8 
: A+10 
: A+12 
: A+14 

ZK-4201-85 


REAL 

PART 


IMAGINARY 

PART 


S EXPONENT FRACTION 


FRACTION 


FRACTION 


FRACTION 


S EXPONENT FRACTION 


FRACTION 


FRACTION 


FRACTION 
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VMS Data Types 

A.1 VMS Data Types 


Table A-1 (Cont.) 
Data Type 

cond—value 


VMS Data Types 
Definition 


Unsigned longword integer denoting a 
condition value (that is, a return status 
or system condition code) that is typically 
returned by a procedure in RO. The structure 
of a condition value is as follows: 


31 28 27 


3 2 0 



facility number 


message number 


ZK-1795-84 

Depending on your specific needs, you can 
test just the low-order bit, the low-order three 
bits, or the entire value. 

• The low-order bit indicates successful 

(1) or unsuccessful (0) completion of the 
service. 

• The low-order three bits taken together 
represent the severity of the error. 

• The remaining bits <31:3> classify 
the particular return condition and the 
operating system component that issued 
the condition value. 

Each numeric condition value has a unique 
symbolic name in the following format, where 
code is a mnemonic describing the return 
condition: 

SS$_code 
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VMS Data Types 

A.1 VMS Data Types 



Table A-1 (Cont.) VMS Data Types 

Data Type Definition 


context 


date_time 


device_name 


ef_cluster_name 


ef_number 


Unsigned longword used by a called procedure 
to maintain position over an iterative sequence 
of calls. It is usually initialized by the caller, but 
thereafter manipulated by the called procedure. 

Unsigned 64-bit binary integer denoting a 
date and time as the number of elapsed 
100-nanosecond units since 00:00 o'clock, 
November 17, 1858. This VMS data type is 
the same as the data type absolute date and 
time in Table 1-3. 

Character string denoting the 1- to 
15-character name of a device. It can be a 
logical name, but if it Is, it must translate to a 
valid device name. If the device name contains 
a colon (:), the colon and the characters 
past It are ignored. When an underscore (^) 
precedes the device name string. It indicates 
that the string is a physical device name. 

Character string denoting the 1- to 
15-character name of an event flag cluster. 

It can be a logical name, but if it is, it must 
translate to a valid event flag cluster name. 

Unsigned longword integer denoting the 
number of an event flag. Local event flags 
numbered 32 to 63 are available to your 
programs. 
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A.1 VMS Data Types 



Table A-1 (Cent.) VMS Data Types 

Data Type Definition 

exit_handler_block Variable-length structure denoting an exit 

handler control block. This control block, 

which describes the exit handler, Is depicted In 
the following diagram: 


31 0 


forward link (used by VMS onf 

/) 

exit handler address 


these 3 bytes must be 0 

arg. count 

address of condition value (written 

by VMS) 



additional arguments for the 
exit handler; these are optional; 
one argument per longword 



fab 


ZK-1714-84 

Structure denoting an RMS file access block. 


file—protection 



Unsigned word that is a 16-bit mask that 
specifies file protection. The mask contains 
four 4-bit fields, each of which specifies the 
protection to be applied to file access attempts 
by one of the four categories of users, from 
the rightmost field to the leftmost field: (1) 
system users, (2) the file owner, (3) users in 
the same UlC group as the owner, and (4) all 
other users (the world). Each field specifies, 
from the rightmost bit to the leftmost bit: {1) 
read access, (2) write access, (3) execute 
access, (4) delete access. Set bits indicate 
that access is denied. 

The following diagram depicts the 16-bit 
file-protection mask: 


WORLD 

GROUP 

OWNER 

SYSTEM 

D 

E 

W 

R 

D 

E 

W 

R 

D 

E 

W 

R 

D 

E 

W 

R 



13 

12 

11 

10 

9 

8 

7 

6 

5 

4 

3 

2 

1 

0 


ZK-1706-84 
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VMS Data Types 

A.1 VMS Data Types 


Table A-1 (Cont.) VMS Data Types 
Data Type Definition 


floating-point One of the VAX standard floating-point data 

types. These types are F—floating, D—floating, 
G—floating, and H—floating. 

The structure of an F_floating number is as 
follows: 


15 14 7 6 0 

: A 

: A+2 

31 16 

ZK-4197-85 

The structure of a D—floating number is as 
follows: 


s 

EXPONENT 

FRACTION 

FRACTION 


15 14 76 0 

: A 

: A+2 
: A+4 
: A+6 


ZK-4198-85 


S EXPONENT FRACTION 


FRACTION 


FRACTION 


FRACTION 


63 


48 


The structure of a G_floatlng number is as 
follows: 


: A 

: A+2 
: A+4 
: A+6 

63 48 

ZK-4199-85 


15 14 4 3 0 
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VMS Data Types 



A. 


1 VMS Data Types 


Table A—1 (Cent.) VMS Data Types 

Data Type Definition 


The structure of an H_floating number is as 
follows: 


15 14 0 


S EXPONENT 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


FRACTION 



127 113 



: A 

: A+2 
: A+4 
: A+6 
: A+8 
: A+10 
: A+12 
; A+14 


ZK-4196-85 


Unsigned longword specifying the exact 
operations a procedure is to perform. This 
longword has two word-length fields: the 
first field is a number specifying the major 
operation; the second field is a mask or bit 
vector specifying various suboperations within 
the major operation. 

Unsigned longword that identifies an object 
returned by the system. 



function_code 


identifier 
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A.1 VMS Data Types 


Table A-1 (Cent.) VMS Data Types 


Data Type 

Definition 

io_status_block 

Quadword structure containing information 
returned by a procedure that completes 
asynchronously. The information returned 
varies depending on the procedure. The 
following figure illustrates the format of the 
Information written in the lOSB for SYS$OIO: 

31 

16 

15 0 

count 

condition value 

device-dependent Information 


ZK-856-82 

The first word contains a condition value 
indicating the success or failure of the 
operation. The condition values used are 
the same as for all returns from system 
services; for example, SS$_NORMAL indicates 
successful completion. 

The second word contains the number of 
bytes actually transferred In the I/O operation. 
Note that for some devices this word contains 
only the low-order word of the count. 

The second longword contains device¬ 
dependent return information. 

To ensure successful I/O completion and the 
integrity of data transfers, you should check 
the lOSB following I/O requests, particularly 
for device-dependent I/O functions. 
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A.1 VMS Data Types 


Table A-1 (Cont.) VMS Data Types 

Data Type Definition 


itenn_list_2 Structure that consists of one or more item 

descriptors and is terminated by a longword 
containing 0 . Each item descriptor is 
a 2-longword structure that contains three 
fields. The following diagram depicts a single 
item descriptor: 


31 15 0 


item code 

c 

omponent length 

component address 



ZK-1709-84 


The first field is a word in which the service 
writes the length (In characters) of the 
requested component. If the service does 
not locate the component, it returns the value 
0 in this field and In the component address 
field. 

The second field contains a user-supplied, 
word-length symbolic code that specifies 
the component desired. The Item codes are 
defined by the macros specific to the service. 

The third field is a longword in which the 
service writes the starting address of the 
component. This address is within the Input 
string itself. 

item_llst_3 Structure that consists of one or more item 

descriptors and Is terminated by a longword 
containing 0 . Each item descriptor is a 
3-longword structure that contains four fields. 
The following diagram depicts the format of a 
single item descriptor: 


31_ 15 0 


Item code 


buffer length 

buffer address 


return length address 



ZK-1705-84 
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A.1 VMS Data Types 


Table A-1 (Cont.) VMS Data Types 

Data Type Definition 

The first field is a word containing a user- 
supplied integer specifying the length (in bytes) 
of the buffer in which the service writes the 
information. The length of the buffer needed 
depends upon the Item code specified in the 
item code field of the item descriptor. If the 
value of buffer length is too small, the service 
truncates the data. 

The second field is a word containing a user- 
supplied symbolic code specifying the item of 
information that the service is to return. These 
codes are defined by macros specific to the 
service. 

The third field Is a longword containing the 
user-supplied address of the buffer in which 
the service writes the information. 

The fourth field is a longword containing the 
user-supplied address of a word in which 
the service writes the length in bytes of the 
information it actually returned. 

item_list_pair Structure that consists of one or more 

longword pairs, or doublets, and Is terminated 
by a longword containing 0. Typically, the first 
longword contains an integer value such as a 
code. The second longword can contain a real 
or integer value. 

ltem_quota_list Structure that consists of one or more quota 

descriptors and is terminated by a byte 
containing a value defined by the symbolic 
name PQL$_LISTEND. Each quota descriptor 
consists of a 1-byte quota name followed by 
an unsigned longword containing the value for 
that quota. 

lock_id Unsigned longword integer denoting a lock 

identifier. This lock Identifier is assigned to a 
lock by the lock manager facility when the lock 
Is granted. 
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A.1 VMS Data Types 

Table A-1 (Cent.) 

VMS Data Types 

Data Type 

Definition 

lock —Status—block 

Structure into which the lock manager facility 
writes status information about a lock. A 
lock status block always contains at least two 
longwords: the first word of the first longword 
contains a condition value; the second word 
of the first longword is reserved by DIGITAL. 
The second longword also contains the lock 
identifier. 


The lock status block receives the final 
condition value plus the lock identification, and 
optionally contains a lock value block. When 
a request is queued, the lock identification is 
stored in the lock status block even if the lock 
has not been granted. This allows a procedure 
to dequeue locks that have not been granted. 


The condition value is placed in the lock status 
block only when the lock Is granted (or when 
errors occur in granting the lock). 


The following diagram depicts a lock status 
block that Includes the optional 16-byte lock 
value block: 


reserved 


condition value 

lock identification 

16-byte 

(used only wher 

lock value block 

1 LCK$M_VALBLK is set) 


ZK-376-81 


lock_value_block 16-byte block that the lock manager facility 

includes in a lock status block if the user 
requests it. The contents of the lock value 
block are user-defined and are not interpreted 
by the lock manager facility. 

logical-name Character string from 1 to 255 characters 

that identifies a logical name or equivalence 
name to be manipulated by VMS logical name 
system services. Logical names that denote 
specific VMS objects have their own VMS 
types; for example, a logical name identifying a 
device has the VMS type device—name. 

longword-signed Is the same as the data type longword integer 

(signed) in Table 1-3. 
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A.1 VMS Data Types 


Table A—1 (Cent.) VMS Data Types 


Data Type 

longword—unsigned 

mask_byte 

mask_longword 

mask_quadword 

mask_word 

null_arg 

octaword—signed 

octaword—unsigned 


Definition 

Is the same as the data type longword 
(unsigned) in Table 1-3. 

Unsigned byte wherein each bit is interpreted 
by the called procedure. A mask is also 
referred to as a set of flags or as a bit mask. 

Unsigned longword wherein each bit is 
interpreted by the called procedure. A mask 
is also referred to as a set of flags or as a bit 
mask. 

Unsigned quadword wherein each bit is 
interpreted by the called procedure. A mask 
is also referred to as a set of flags or as a bit 
mask. 

Unsigned word wherein each bit is interpreted 
by the called procedure. A mask is also 
referred to as a set of flags or as a bit mask. 

Unsigned longword denoting a null argument. 

A null argument is one whose only purpose is 
to hold a place in the argument list. 

Is the same as the data type octaword integer 
(signed) in Table 1-3. 

Is the same as the data type octaword 
(unsigned) In Table 1-3. 
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A.1 VMS Data Types 


Table A-1 (Cont.) VMS Data Types 

Data Type Definition 

page—protection Unsigned longword specifying page protection 

to be applied by the VAX hardware. 
Protection values are specified using bits 
<3:0> ; bits <31:4> are ignored. 


The $PRTDEF macro defines the following 
symbolic names for the protection codes: 


Symbol 

Description 

PRT$C_NA 

No access 

PRT$C_KR 

Kernel read only 

PRT$C_KW 

Kernel write 

PRT$C_ER 

Executive read only 

PRT$C_EW 

Executive write 

PRT$C_SR 

Supervisor read only 

PRT$C_SW 

Supervisor write 

PRT$C_UR 

User read only 

PRT$C_UW 

User write 

PRT$C_ERKW 

Executive read; kernel 
write 

PRT$C_SRKW 

Supervisor read; kernel 
write 

PRT$C_SREW 

Supervisor read; executive 
write 

PRT$C_URKW 

User read; kernel write 

PRT$C_UREW 

User read; executive write 

PRT$C_URSW 

User read; supervisor write 


If you specify the protection as 0, the 
protection defaults to kernel read only. 

procedure Unsigned longword denoting the entry mask 

to a procedure that is not to be called at AST 
level. (Arguments specifying procedures to 
be called at AST level have the VMS type 
ast—procedure.) 

process_id Unsigned longword Integer denoting a process 

identification (PID). This process Identification 
is assigned to a process by VMS when the 
process Is created. 

process_name Character string, containing 1 to 15 characters, 

that specifies the name of a process. 

quadword—signed Is the same as the data type quadword 

integer (signed) in Table 1-3. 

quadword—unsigned Is the same as the data type quadword 

(unsigned) in Table 1-3. 
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A.1 VMS Data Types 


Table A-1 (Cont.) VMS Data Types 

Data Type Definition 

rights—holder Unsigned quadword specifying a user's access 

rights to a system object. This quadword 
consists of two fields: the first is an unsigned 
longword identifier (VMS type rights_id), 
and the second is a longword bit mask 
wherein each bit specifies an access right. 

The following diagram depicts the format of a 
rights holder: 


rights_id 


UlC identifier of holder 


0 


ZK-1903-84 


Unsigned longword denoting a rights identifier, 
which identifies an interest group in the 
context of the VMS security environment. 

This rights environment may consist of all or 
part of a user's user identification code (UlC). 

Identifiers have two formats in the rights 
database: UlC format (VMS type uic) and ID 
format. The high-order bits of the identifier 
value specify the format of the identifier. Two 
high-order zero bits identify a UIC format 
identifier; bit <31 > , set to 1, identifies an ID 
format identifier. 

Bit <31 > , set to 1, specifies ID format. Bits 
<30:28> are reserved by DIGITAL. The 
remaining bits specify the identifier value. The 
following diagram depicts the ID format of a 
rights Identifier: 


31 


0 


1000 


identifier 


ID Format 


ZK-1906-84 


To the system, an identifier is a binary value; 
however, to make identifiers easy to use, the 
system translates the binary identifier value 
into an Identifier name. The binary value and 
the identifier name are associated in the rights 
database. 
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Table A-1 (Cont.) VMS Data Types 

Data Type Definition 

An identifier name consists of 1 to 31 
alphanumeric characters and contains at least 
one nonnumeric character. An identifier name 
cannot consist entirely of numeric characters. 

It can include the characters A through Z, 
dollar signs ($) and underscores (_), as well 
as the numbers 0 through 9. Any lowercase 
characters are automatically converted to 
uppercase. 

rab Structure denoting an RMS record access 

block. 

Unsigned quadword denoting a global section 
identifier. This identifier specifies the version 
of a global section and the criteria to be used 
in matching that global section. 

Character string denoting a 1- to 43-character 
global-section name. This character string can 
be a logical name, but it must translate to a 
valid global-section name. 

Unsigned quadword that denotes a system 
identification value to be associated with a 
rights database. 

Character string specifying a time value in VMS 
format. 

uic Unsigned longword denoting a user 

identification code (UIC). Each UIC is unique 
and represents a system user. The UIC 
identifier contains two high-order bits that 
designate format, a member field, and a 
group field. Member numbers range from 0 
to 65,534; group numbers range from 1 to 
16,382. The following diagram depicts the 
UIC format: 


31 

0 

00 

group 


member 




UIC Format 

ZK-1905-84 


user_arg Unsigned longword d noting a user-defined 

argument. This longword Is passed to a 
procedure as an argument, but the contents of 
the longword are defined and interpreted by 
the user. 


section _ld 


section—name 


system —access—id 


time—name 
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A.1 VMS Data Types 


Table A-1 (Cont.) VMS Data Types 


Data Type 

Definition 

varying—arg 

Unsigned longword denoting a variable 
argument. A variable argument can have 
variable types, depending on specifications 
made for other arguments In the call. 

vector—byte—signed 

A homogeneous array whose elements are all 
signed bytes. 

vector—byte—unsigned 

A homogeneous array whose elements are all 
unsigned bytes. 

vector—longword—signed 

A homogeneous array whose elements are all 
signed longwords. 

vector—longword—unsigned 

A homogeneous array whose elements are all 
unsigned longwords. 

vector—quadword—signed 

A homogeneous array whose elements are all 
signed quadwords. 

vector—quadword—unsigned 

A homogeneous array whose elements are all 
unsigned quadwords. 

vector—word—signed 

A homogeneous array whose elements are all 
signed words. 

vector—word—unsigned 

A homogeneous array whose elements are all 
unsigned words. 

word—signed 

Is the same as the data type word integer 
(signed) in Table 1-3. 

word—unsigned 

Is the same as the data type word (unsigned) 
In Table 1-3. 


VAX Ada Implementation 

Table A-2 lists the VMS data types and their corresponding VAX® Ada® 
data-type declarations. 

Table A-2 VAX Ada Implementation 

VMS Data Structure VAX Ada Declaration 


access_bit—names 
access—mode 
address 
address—range 
arg—list 
ast-procedure 


STARLET.ACCESS-BIT-NAMES-TYPE 
STARLET.ACCESS-MODE-TYPE 
SYSTEM.ADDRESS 
STARLET.ADDRESS-RANGE-TYPE 
STARLET.ARG-LIST-TYPE 
SYSTEM.AST-HANDLER 




VAX is a trademark of Digital Equipment Corporation. 

Ada is a registered trademark of the U.S. Government, Ada Joint Program Office. 
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A.2 VAX Ada Implementation 


Table A-2 (Cent.) 

VAX Ada Implementation 

VMS Data Structure 

VAX Ada Declaration 

boolean 

STANDARD.BOOLEAN 

byte_signed 

byte_unsigned 

channel 

STANDARD.SHORT_SHORT_INTEGER 

SYSTEM.UNSIGNED_BYTE 

STARLET.CHANNEL_TYPE 

char_string 

complex_number 

cond_value 

STANDARD.STRING 

User-defined record 

CONDITION-HANDLING.COND-VALUE-TYPE 

context 

STARLET.CONTEXT-TYPE 

date_time 

STARLET.DATE_TIME_TYPE 

device_name 

STARLET.DEVICE_NAME_TYPE 

ef_cluster_name 

STARLET.EF_CLUSTER_NAME_TYPE 

ef_number 

STARLET.EF-NUMBER-TYPE 

exit_handler_block 

STARLET.EXIT_HANDLER_BLOCK_TYPE 

fab 

STARLET.FAB-TYPE 

file—protection 

floating-point 

STARLET.FILE_PROTECTION_TYPE 

STANDARD.FLOAT 

STANDARD.LONG-FLOAT 

STANDARD.LONG_LONG_FLOAT 

SYSTEM.F_FLOAT 

SYSTEM.D_FLOAT 

SYSTEM.G_FLOAT 

SYSTEM.H_FLOAT 

function—code 

STARLET.FUNCTION_CODE_TYPE 

identifier 

SYSTEM-UNSIGNED-LONGWORD 

io—status—block 

STARLET. IOSB_TYPE 

item—list—pair 

item—list—2 

SYSTEM.UNSIGNED_LONGWORD 

STARLET.ITEM_LIST_2_TYPE 

item—list—3 

STARLET.ITEM_LIST_TYPE 

item—quota—list 

lock—id 

User-defined record 

STARLET.LOCK_ID_TYPE 

lock—status—block 

STARLET.LOCK_STATUS_BLOCK_TYPE 

lock—value—block 

STARLET.LOCK_VALUE_BLOCK_TYPE 

logical-name 
longword—signed 
longword—unsigned 
mask—byte 
mask—longword 
mask—quadword 

mask—word 

STARLET.LOGICAL_NAME_TYPE 

STANDARD.INTEGER 

SYSTEM.UNSIGNED-LONGWORD 

SYSTEM.UNSIGNED_BYTE 

SYSTEM.UNSIGNED-LONGWORD 

SYSTEM.UNSIGNED-QUADWORD 

SYSTEM.UNSIGNED_WORD 

null—arg 

SYSTEM. UNSIGNED-LONG WORD 
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A.2 VAX Ada Implementation 


Table A-2 (Cent.) VAX Ada Implementation 

VMS Data Structure VAX Ada Declaration 


octaword—signed 

octaword—unsigned 

page—protection 

procedure 

process_id 

process_name 

quadword—signed 

quadword—unsigned 

rights—holder 

rights_id 

rab 

section_id 

section_name 

system _access_id 

time_name 

uic 

user_arg 

varying_arg 

vector_byte_signed 

vector_byte_unsigned 

vector_longword_signed 

vector_longword_unsigned 

vector_quadword_signed 

vector_quadword_unsigned 

vector_word_signed 

vector_word_unsigned 

word—signed 

word—unsigned 


array(1..4) of SYSTEM.UNSIGNED_LONGWORD 

array(1..4) of SYSTEM.UNSIGNED_LONGWORD 

STARLET.PAGE_PROTECTION_TYPE 

SYSTEM.ADDRESS 

STARLET.PROCESS_ID_TYPE 

STARLET.PROCESS_NAME_TYPE 

SYSTEM.UNSIGNED.QUADWORD 

SYSTEM.UNSIGNED^QUADWORD 

STARLET.RIGHTS_HOLDER_TYPE 

STARLET.RIGHTS_ID_TYPE 

STARLET.RAB_TYPE 

STARLET.SECTION_ID_TYPE 

STARLET.SECTION_NAME_TYPE 

STARLET.SYSTEM_ACCESS_ID_TYPE 

STARLET.TIME_NAME_TYPE 

STARLET.UIC_TYPE 

STARLET.USER_ARG«TYPE 

SYSTEM.UNSIGNED_LONGWORD 

array(l..n) of STANDARD.SHORT_SHORT_INTEGER 

array(l..n) of SYSTEM.UNSIGNED_BYTE 

array(1..n) of STANDARD.INTEGER 

array(1..n) of SYSTEM.UNSIGNED_LONGWORD 

array(1..n) of SYSTEM.UNSIGNED.QUADWORD 

array(1..n) of SYSTEM.UNSIGNED_QUADWORD 

array(1..n) of STANDARD.SHORT_INTEGER 

array(1..n) of SYSTEM.UNSIGNED.WORD 

STANDARD.SHORT_INTEGER 

SYSTEM.UNSIGNED_WORD 


A.3 VAX APL Implementation 

Table A-3 lists the VMS data types and their corresponding VAX APL 
data-type declarations. 
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V 

A.3 VAX 

Table A—3 VAX APL Implementation 

^MS Data Types 

APL Implementation 

VMS Data Type 

VAX APL Declaration 

access_bit_names 

NA 


access_mode 

/TYPE= 

=BU 

address 

NA 


address_range 

NA 


arg_list 

NA 


ast_procedure 

NA 


boolean 

/TYPE= 

=V 

byte_signed 

/TYPE= 

=B 

byte_unsigned 

/TYPE= 

=BU 

channel 

/TYPE= 

=WU 

char_string 

/TYPE= 

=T 

complex-number 

/TYPE= 

=FC 


/TYPE= 

=DC 


/TYPE=GC 


/TYPE= 

=HC 

cond—value 

/TYPE= 

=LU 

context 

NA 


date—time 

NA 


device—name 

/TYPE= 

=T 

ef—cluster—name 

/TYPE= 

=T 

ef—number 

/TYPE= 

=LU 

exit—handler—block 

NA 


fab 

NA 


file-protection 

/TYPE= 

=WU 

floating-point 

/TYPE= 

=F 


/TYPE= 

=D 


/TYPE= 

=G 


/TYPE= 

=H 

function—code 

NA 


identifier 

NA 


io—status—block 

NA 


item—list—2 

NA 


item—list—3 

NA 


item—list—pair 

NA 


item—quota—list 

NA 


lock—id 

/TYPE’ 

^LU 

lock—status—block 

NA 


lock—value—block 

NA 


logical—name 

/TYPE’ 

-T 

1 
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Table A—3 (Cent.) VAX APL Implementation 


VMS Data Type 

VAX APL Declaration 

longword—signed 

/TYPE=L 

longword—unsigned 

/TYPE=LU 

mask_byte 

/TYPE=BU 

mask—longword 

/TYPE=LU 

mask^quadword 

NA 

mask_word 

/TYPE=WU 

null_arg 

/TYPE=LU 

octaword—signed 

NA 

octaword—unsigned 

NA 

page—protection 

/TYPE=LU 

procedure 

NA 

process_id 

/TYPE=LU 

process_name 

/TYPE=T 

quadword—signed 

NA 

quadword—unsigned 

NA 

rights—holder 

NA 

rights_id 

/TYPE=LU 

rab 

NA 

section _id 

NA 

section—name 

/TYPE=T 

system _access_id 

NA 

time_name 

/TYPE=T 

uic 

/TYPE=LU 

user_arg 

/TYPE=LU 

varying_arg 

NA 

vector_byte_signed 

/TYPE=B 

vector_byte_unsigned 

/TYPE=BU 

vector_longword_signed 

/TYPE=L 

vector_longword_unsigned 

/TYPE=LU 

vector_quadword_signed 

NA 

vector_quadword_unsigned 

NA 

vector_word_signed 

/TYPE=W 

vector_word_unsigned 

/TYPE=WU 

word—signed 

/TYPE=W 

word—unsigned 

/TYPE=WU 
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A.4 VAX BASIC Implementation 

Table A-4 lists the VMS data types and their corresponding VAX BASIC 
data-type declarations. 


Table A-4 VAX BASIC Implementation 


VMS Data Type 

VAX BASIC Declaration 

access_bit_names 

NA 

access_mode 

BYTE (signed) 

address 

LONG 

address_range 

LONG address_range (1) 
or 

RECORD address_range 

LONG beginning_address 

LONG ending_address 

END RECORD 

arg_list 

NA 

ast_procedure 

EXTERNAL LONG ast_proc 

boolean 

LONG 

byte_signed 

BYTE 

byte_unsigned 

BYTE’ 

channel 

WORD 

char_string 

STRING 

complex_number 

RECORD complex 

REAL real—part 

REAL imaginary_part 

END RECORD 

cond—value 

LONG 

context 

LONG 

date_time 

RECORD date_time 

LONG FILL (2) 

END RECORD 

device_name 

STRING 

ef_cluster_name 

STRING 

ef_number 

LONG 

exit_handler_block 

RECORD EHCB 

LONG flink 

LONG handler_addr 

BYTE arg_count 

BYTE FILL (3) 

LONG status_value_addr 

END RECORD 

fab 

NA 


'Although unsigned data types are not directly supported in VAX BASIC, you may 
substitute the signed equivalent provided you do not exceed the range of the signed data 
type. 
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Table A-4 (Cent.) 

VAX BASIC Implementation 

VMS Data Type 

VAX BASIC Declaration 

file_protection 

floating-point 

LONG 

SINGLE 

DOUBLE 

GFLOAT 

HFLOAT 

function_code 

RECORD function-code 

WORD major-function 

WORD subfunction 

END RECORD 

identifier 

LONG 

io—status—block 

RECORD iosb 

WORD iosb-field (3) 

END RECORD 

item_list_2 

RECORD item—list—two 

GROUP item(15) 

VARIANT 

CASE 

WORD comp—length 

WORD code 

LONG comp—address 

CASE 

LONG terminator 

END VARIANT 

END GROUP 

END RECORD 

item—list—3 

RECORD item—list—3 

GROUP item (15) 

VARIANT 

CASE 

WORD buf-len 

WORD code 

LONG buffer—address 

\ 

LONG length—address 

CASE 

LONG terminator 

END VARIANT 

END GROUP 

END RECORD 

item—list—pair 

RECORD item—list—pair 

GROUP item (15) 

VARIANT 

CASE 

LONG code 

LONG value 

CASE 

LONG terminator 

END VARIANT 

END GROUP 

END RECORD Item—list—pair 
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Table A-4 (Cent.) 

VAX BASIC Implementation 

VMS Data Type 

VAX BASIC Declaration 

item_quota_list 

RECORD item—quota—list 

GROUP quota (n) 

VARIANT 

CASE 

, BYTE quota—name 

LONG value 

CASE 

BYTE list-end 

END VARIANT 

END GROUP 

END RECORD 

lock_id 

LONG 

lock_status_block 

NA 

lock_value_block 

NA 

logical-name 

STRING 

longword—signed 

LONG 

longword—unsigned 

LONG’ 

mask—byte 

BYTE 

mask—longword 

LONG 

mask—quadword 

RECORD quadword 

LONG FILL (2) 

END RECORD’ 

mask—word 

WORD 

null—arg 

A null argument is indicated by a comma 
used as a placeholder in the argument list. 

octaword—signed 

NA 

octaword—unsigned 

NA 

page—protection 

LONG 

procedure 

EXTERNAL LONG proc 

process—id 

LONG 

process—name 

STRING 

quadword—signed 

RECORD quadword 

LONG FILL (2) 

END RECORD 

quadword—unsigned 

RECORD quadword 

LONG FILL (2) 

END RECORD’ 

rights—holder 

RECORD quadword 

LONG FILL (2) 

END RECORD’ 

rights—id 

LONG 

^Although unsigned data types are not directly supported in VAX BASIC, you may 
substitute the signed equivalent provided you do not exceed the range of the signed data 
type. 
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Table A-4 (Cont.) VAX BASIC Implementation 


VMS Data Type 

VAX BASIC Declaration 

rab 

NA 

section_id 

RECORD quadword 

LONG FILL (2) 

END RECORD^ 

section_name 

STRING 

system _access_id 

RECORD quadword 

LONG FILL (2) 

END RECORD^ 

time_name 

STRING 

uic 

LONG 

user_arg 

LONG 

varying_arg 

Dependent upon application. 

vector_byte_signed 

BYTE array (n) 

vector_byte_unsigned 

BYTE array (n)^ 

vector_longword_signed 

LONG array (n) 

vector_longword_unsigned 

LONG array (n)^ 

vector_quadword_signed 

NA 

vector_quadword_unsigned 

NA 

vector_word_signed 

WORD array (n) 

vector_word_unsigned 

WORD array (n)’ 

word_signed 

WORD 

word—unsigned 

WORD^ 

^Although unsigned data types are not directly supported in VAX BASIC, you may 
substitute the signed equivalent provided you do not exceed the range of the signed data 
type. 


A.5 VAX BLISS Implementation 

Table A-5 lists the VMS data types and their corresponding VAX BLISS 
data-type declarations. 
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Table A-5 VAX BLISS Implementation 


VMS Data Type 

VAX BLISS Declaration 

access—bit—names 

access_mode 

BLOCKVECTOR(32,8,BYTE] 

UNSIGNED BYTE 

address 

UNSIGNED LONG 

address—range 
arg—list 

VECTOR[2,LONG,UNSIGNED] 

VECTOR[n,LONG,UNSIGNED] 

where n is the number of arguments + 1. 

ast—procedure 

boolean 

UNSIGNED LONG 

UNSIGNED LONG 

byte—signed 
byte—unsigned 

channel 

char—string 
complex—number 

SIGNED BYTE 

UNSIGNED BYTE 

UNSIGNED WORD 

VECTOR[65536,BYTE,UNSIGNED] 

F_Complex: VECTOR[2,LONG] 

D_Complex: VECTOR[4,LONG] 

G_Complex: VECTOR[4,LONG] 

H_Complex: VECTOR[8,LONG] 

cond—value 

UNSIGNED LONG 

context 

UNSIGNED LONG 

date—time 

device—name 

VECTOR[2,LONG,UNSIGNED] 

VECTOR(n,BYTE,UNSIGNED] 

where n is the length of the device name. 

ef—cluster—name 

VECTOR[n,BYTE,UNSIGNED] 
where n is the length of the event flag 
cluster name. 

ef—number 

exit—handler—block 

UNSIGNED LONG 

BLOCK[n,BYTE] 

where n is the size of the exit handler 
control block. 

fab 

$FAB_DECL (from STARLET.REQ) 

file-protection 
floating-point 

BLOCK(2,BYTE] 

F_Floating: VECTOR] 1,LONG] 

D_Floating: VECTOR[2,LONG] 

G_Floating: VECTOR[2,LONG] 

H_Floating: VECT0R[4,L0NG] 

function—code 

identifier 

BLOCK[2,WORD] 

UNSIGNED LONG 

io—status—block 

item-list—2 

BLOCK[8,BYTE] 

BLOCKVECTOR[n,8,BYTE] 
where n is the number of the item 
descriptors + 1. 
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Table A-5 (Cont.) VAX BLISS Implementation 


VMS Data Type 

item_list_3 


item_list_pair 


item_quota_list 


lock_id 

lock_status_block 


lock_value_block 
logical-name 
longword—signed 
longword—unsigned 
mask-byte 
mask—longword 
mask—quadword 
mask—word 
null—arg 

octaword—signed 
octaword—unsigned 
page—protection 
procedure 
process—id 
process—name 

quadword—signed 
quadword—unsigned 
rights—holder 
rights—id 
rab 

section—id 
section—name 


system —access—id 


VAX BLISS Declaration 

BLOCKVECTOR[n, 12,BYTE] 
where n is the number of the item 
descriptors + 1. 

$ITMLST-DECL/$ITMLST-INIT 
from STARLET.REQ 

BLOCKVECTOR[n,2,LONG] 
where n is the number of the item 
descriptors + 1. 

BL0CKVECT0R[n,53YTE] 
where n is the number of the quota 
descriptors + 1. 

UNSIGNED-LONG 

BLOCK[n,BYTE] 

where n is the size of the 

lock—status—block minus at least 8. 

BL0CK[16,BYTE] 

VECTOR[255,BYTE,UNSIGNED] 

SIGNED LONG 
UNSIGNED LONG 
BITVECTOR[8] 

BITVECTOR[32] 

BITVECTOR[64] 

BITVECTOR[16] 

UNSIGNED LONG 
VECTOR[4,LONG,UNSIGNED] 
VECTOR[4,LONG,UNSIGNED] 

UNSIGNED LONG 
UNSIGNED LONG 
UNSIGNED LONG 

VECTOR[n,BYTE,UNSIGNED] 

where n is the length of the process name. 

VECTOR[2,LONG,UNSIGNED] 

VECTOR[2,LONG,UNSIGNED] 

BLOCK[8,BYTE] 

UNSIGNED LONG 

$RAB-DECL 
from STARLET.REQ 

VECTOR[2,LONG,UNSIGNED] 

VECTOR[n,BYTE,UNSIGNED] 

where n is the length of the global section 

name. 

VECTOR[2,LONG,UNSIGNED] 
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Table A-5 (Cent.) VAX BLISS Implementation 

VMS Data Type 

VAX BLISS Declaration 

time_name 

VECTOR[n,BYTE,UNSIGNED] 

where n is the length of the time value in 

VMS format. 

uic 

UNSIGNED LONG 

user_arg 

UNSIGNED LONG 

varying_arg 

UNSIGNED LONG 

vector_byte_signed 

VECTOR[n,BYTE,SIGNED] 
where n is the size of the array. 

vector_byte_unsigned 

VECTOR[n,BYTE,UNSIGNED] 
where n is the size of the array. 

vector_longword_signed 

VECTOR[n,LONG,SIGNED] 
where n is the size of the array. 

vector_longword_unsigned 

VECTOR[n,LONG,UNSIGNED] 
where n is the size of the array. 

vector_quadword_signed 

BLOCKVECTOR[n,2,LONG] 
where n is the size of the array. 

vector_quadword_unsigned 

BLOCKVECTOR[n,2,LONG] 
where n is the size of the array. 

vector_word_signed 

VECTOR[n,BYTE,SIGNED] 
where n is the size of the array. 

vector_word_unsigned 

VECTOR[n,BYTE,UNSIGNED] 
where n is the size of the array. 

word—signed 

SIGNED WORD 

word—unsigned 

UNSIGNED WORD 


VAX C Implementation 

Table A-6 lists the VMS data types and their corresponding VAX C data-type 
declarations. 
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Table A-6 VAX C Implementation 


VMS Data Type 

VAX C Declaration 

access_bit—names 

User-defined^ 

access_mode 

unsigned char 

address 

int *pointer^’^ 

address_range 

int ‘array 

arg_list 

User-defined^ 

ast—procedure 

Pointer to function.^ 

boolean 

unsigned long Int 

byte_signed 

char 

byte—unsigned 

unsigned char 

channel 

unsigned short int 

char—string 

char array[nf 

complex—number 

User-defined^ 

cond—value 

unsigned long int 

context 

unsigned long int 

date-time 

User-defined^ 

device—name 

char array[nf 

ef—cluster—name 

char array[n]^’® 

ef—number 

unsigned long int 

exit—handler—block 

User-defined^ 

fab 

#include fab from text library 
struct FAB 

file—protection 

unsigned short int or user-defined^ 

floating-point 

float or double 

function-code 

unsigned long int or user-defined’ 

identifier 

Int ♦pointer'^ '^ 

io—status—block 

User-defined’ 

item—list—2 

User-defined’ 

item—list—3 

User-defined’ 

item—list—pair 

User-defined’ 

Item—quota—list 

User-defined’ 

lock—id 

unsigned long int 

lock—status—block 

User-defined’ 

lock—value—block 

User-defined’ 


^The declaration of a user-defined data structure depends on how the data will be used. Such data structures can be 
declared in a variety of ways, each of which is suitable only to specific applications. 

^The term pointer refers to several declarations involving pointers. Pointers are declared with special syntax and 
associated with the data type of the object being pointed to. This object is often user-defined. 

^The term array denotes the syntax of a VAX C array declaration. 

^The data type specified can be changed to any valid VAX C data type. 

^The size of the array must be substituted for n. 

A-30 










VMS Data Types 

A.6 VAX C Implementation 


Table A-6 (Cont.) VAX C Implementation 


VMS Data Type VAX C Declaration 


logical-name 

char array[nf 

longword—signed 

long int 

longword—unsigned 

unsigned long int 

mask—byte 

unsigned char 

mask—longword 

unsigned long int 

mask—quadword 

User-defined^ 

mask—word 

unsigned short int 

null—arg 

unsigned long int 

octaword—signed 

User-defined^ 

octaword—unsigned 

User-defined^ 

page—protection 

unsigned long int 

procedure 

Pointer to function^ 

process—id 

unsigned long int 

process—name 

char array[nf 

quadword—signed 

User-defined^ 

quadword—unsigned 

User-defined^ 

rights—holder 

User-defined^ 

rights-id 

unsigned long int 

rab 

#include rab from text library 
struct RAB 

section—id 

User-defined^ 

section—name 

char array[nf 

system —access—id 

User-defined^ 

time—name 

char array[nf 

uic 

unsigned long int 

user—arg 

User-defined^ 

varying—arg 

User-defined^ 

vector—byte—signed 

char array[n]^’® 

vector—byte—unsigned 

unsigned char array[nf 

vector—longword—signed 

long int array[nf 

vector—longword—unsigned 

unsigned long int array[n]^’® 

vector—quadword—signed 

User-defined’ 

vector—quadword—unsigned 

User-defined’ 

vector—word—signed 

short int array[nf 


^The declaration of a user-defined data structure depends on how the data will be used. Such data structures can be 
declared in a variety of ways, each of which is suitable only to specific applications. 

^The term pointer refers to several declarations involving pointers. Pointers are declared with special syntax and 
associated with the data type of the object being pointed to. This object is often user-defined. 

^The term array denotes the syntax of a VAX C array declaration. 

^The size of the array must be substituted for n. 
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A.7 


Table A-6 (Cont.) VAX C Implementation 

VMS Data Type VAX C Declaration 

vector_word_unsigned unsigned short int array[nf 

word—signed short int 

word_unsigned unsigned short int 

^The term array denotes the syntax of a VAX C array declaration. 

^The size of the array must be substituted for n. 


VAX COBOL Implementation 

Table A-7 lists the VMS data types and their corresponding VAX COBOL 
data-type declarations. 


Table A~7 VAX COBOL Implementation 


VMS Data Type 

VAX COBOL Declaration 

access_bit—names 

NA . . . PIC X( 128)2 

access_mode 

NA . . . PIC X2 

access—mode is usually passed BY VALUE 
as PIC 9(5) COMP 

address 

USAGE POINTER 

address—range 

01 ADDRESS-RANGE 

02 BEGINNING-ADDRESS USAGE POINTER 
02 ENDING-ADDRESS USAGE POINTER 

arg_list 

NA . . . Constructed by the compiler as a result of 
using the COBOL CALL statement. An argument 
list may be created as follows, but cannot be 
referenced by the COBOL CALL statement. 

01 ARG-LIST 

02 ARG-COUNT PIC S9(5) COMP 

02 ARG-BY-VALUE PIC S9(5) COMP 

02 ARG-BY-REFERENCE USAGE POINTER 

02 VALUE REFERENCE ARG-NAME 
. . . continue as needed 

ast—procedure 

01 AST-PROC PIC 9(5) COMP’ 

boolean 

01 BOOLEAN-VALUE PIC 9(5) COMP’ 

byte_signed 

NA . . . PIC X2 

byte_unsigned 

NA . . . PIC X2 


^Although unsigned computational data structures are not directly supported in VAX 
COBOL, you may substitute the signed equivalent provided you do not exceed the range of 
the signed data structure. 


^Most VMS data types not directly supported in VAX COBOL can be represented as 
an alphanumeric data item of a certain number of bytes. While VAX COBOL does not 
Interpret the data type, it may be used to pass objects from one language to another. 
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Table A—7 (Cent.) VAX COBOL Implementation 


VMS Data Type VAX COBOL Declaration 


channel 

01 CHANNEL PIC 9(4) COMP' 

char_string 

01 CHAR-STRING PIC X to PIC X(65535) 

complex_number 

NA . . . PIC X(n) where n is length^ 

cond_value 

01 COND-VALUE PIC 9(5) COMP’ 

context 

01 CONTEXT PIC 9(5) COMP’ 

date_time 

NA . . . PIC X(16)2 


device_name 

01 DEVICE-NAME PIC X(n) where n is length. 

ef_cluster_name 

01 CLUSTER-NAME 

PIC X(n) where n is length. 

ef_number 

01 EF-NO PIC 9(5) COMP^ 

exit_handler_block 

NA . . . PIC X(n) where n is length^ 

fab 

NA ... Too complex for general COBOL use. 

Most of a FAB structure can be described by 
a lengthy COBOL record description, but such 
a FAB cannot then be referenced by a COBOL 

1-0 statement. It is much simpler to do the 1-0 
completely within COBOL, and let the COBOL 
compiler generate the FAB structure, or do the 1-0 
In another language. 

file_protection 

01 FILE-PROT PIC 9(4) COMP’ 

floating-point 

01 F-FLOAT USAGE COMP-1 

01 D-FLOAT USAGE COMP-2 
g-float and h-float are not supported In 

VAX COBOL. 

function—code 

01 FUNCTION-CODE 

02 MAJOR-FUNCTION PIC 9(4) COMP’ 

02 SUB-FUNCTION PIC 9(4) COMP’ 

identifier 

01 ID PIC 9(5) COMF 

.1 

io—status—block 

01 lOSB 

02 COND-VAL 
02 BYTE-CNT 
02 DEV-INFO 1 

PIC 9(4) COMP’ 

PIC 9(4) COMP’ 

^IC 9(5) COMP’ 

item—list-2 

01 ITEM-LIST-TWO 

02 ITEM-LIST OCCURS n TIMES 

04 COMP-LENGTH PIC S9(4) COMP 

04 ITEM-CODE PIC S9(4) COMP 

04 COMP-ADDRESS PIC S9(5) COMP 

02 TERMINATOR PIC S9(5) COMP VALUE 

0 

^Although unsigned computational data structures are not directly supported In VAX 
COBOL, you may substitute the signed equivalent provided you do not exceed the range of 
the signed data structure. 

^Most VMS data types not directly supported in VAX COBOL can be represented as 
an alphanumeric data item of a certain number of bytes. While VAX COBOL does not 
interpret the data type, it may be used to pass objects from one language to another. 
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Table A-7 (Cont.) 

VAX COBOL Implementation 

VMS Data Type 

VAX COBOL Declaration 

itenn_list_3 

01 ITEM-LIST-3 


02 ITEM-LIST OCCURS n TIMES 
04 BUF-LEN PIC S9(4) COMP 
04 ITEM-CODE PIC S9{4) COMP 
04 BUFFER-ADDRESS PIC S9(5) COMP 
04 LENGTH-ADDRESS PIC S9(5) COMP 
02 TERMINATOR PIC S9(5) COMP VALUE 

0 


item_list_pair 

01 ITEM-LIST-PAIR 

02 ITEM-LIST OCCURS n TIMES 

04 ITEM-CODE PIC S9{5) COMP 

04 ITEM-VALUE PIC S9(5) COMP 

02 TERMINATOR PIC S9(5) COMP VALUE 

0 

item_quota_list 

NA 

lock_id 

01 LOCK-ID PIC 9(5) COMP’ 

lock_status_block 

NA 

lock_value_block 

NA 

logical_name 

01 LOG-NAME PIC X TO X(255) 

longword—signed 

01 LWS PIC S9{5) COMP 

longword—unsigned 

01 LWU PIC 9(5) COMP' 

mask_byte 

NA . . . PIC X^ 

mask_longword 

01 MLW PIC 9(5) COMP’ 

mask_quadword 

01 MOW PIC 9(18) COMP’ 

mask_word 

01 MW PIC 9(4) COMP’ 

null_arg 

CALL . . . USING OMITTED or 

PIC S9(5) COMP VALUE 0 
passed USING BY VALUE 

octaword—signed 

NA 

octaword—unsigned 

NA 

page—protection 

01 PAGE-PROT PIC 9(5) COMP’ 

procedure 

01 ENTRY-MASK PIC 9(5) COMP’ 

process_id 

01 PID PIC 9(5) COMP’ 

process_name 

01 PROCESS-NAME PIC X TO X(15) 

quadword—signed 

01 QWS PIC S9(18) COMP 

quadword—unsigned 

01 QWU PIC 9(18) COMP’ 


^Although unsigned computational data structures are not directly supported In VAX 
COBOL, you may substitute the signed equivalent provided you do not exceed the range of 
the signed data structure. 


2Most VMS data types not directly supported In VAX COBOL can be represented as 
an alphanumeric data item of a certain number of bytes. While VAX COBOL does not 
interpret the data type, it may be used to pass objects from one language to another. 
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Table A-7 (Cent.) VAX COBOL Implementation 

VMS Data Type 

VAX COBOL Declaration 

rights—holder 

01 RIGHTS-HOLDER 

02 RIGHTS-ID PIC 9(5) COMP’ 

02 ACCESS-RIGHTS PIC 9(5) COMP’ 

rights_id 

01 RIGHTS-ID PIC 9(5) COMP’ 

rab 

NA ... Too complex for general COBOL use. 

Most of a RAB structure can be described by 
a lengthy COBOL record description, but such 
a RAB cannot then be referenced by a COBOL 

1-0 statement. It is much simpler to do the 1-0 
completely within COBOL, and let the COBOL 
compiler generate the RAB structure, or do the 1-0 
in another language. 

section_ld 

01 SECTION-ID PIC 9(18) COMP’ 

section—name 

01 SECTION-NAME PIC X to X(43) 

system —access—id 

01 SECTION-ACCESS-ID PIC 9(18) COMP’ 

time—name 

01 TIME-NAME PIC X(n) where n is the length. 

uic 

01 UIC PIC 9(5) COMP’ 

user—arg 

01 USER-ARG PIC 9(5) COMP’ 

varying—arg 

Dependent upon application 

vector—byte—signed 

NA . ..3 

vector—byte—unsigned 

NA . . .3 

vector—longword—signed 

NA . . .3 

vector—longword—unsigned 

NA . . . ’^ 

vector—quadword—signed 

NA . ..^ 

vector—quadword—unsigned 

NA . . .^ 

vector—word—signed 

NA . ..® 

vector—word—unsigned 

NA . . .^ 

word—signed 

01 WS PIC S9(4) COMP 

word—unsigned 

01 WS PIC 9(4) COMP’ 


^Although unsigned computational data structures are not directly supported in VAX 
COBOL, you may substitute the signed equivalent provided you do not exceed the range of 
the signed data structure. 

^VAX COBOL does not permit the passing of variable-length data structures. 


A.8 VAX FORTRAN Implementation 

Table A-8 lists the VMS data types and their corresponding VAX FORTRAN 
data-type declarations. 
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Table A-8 VAX FORTRAN Implementation 


VMS Data Type 

VAX FORTRAN Declaration 

access_bit—names 

INTEGER»4(2,32) 

or 

STRUCTURE /access_bit_names/ 

INTEGER*4 access_name_len 
INTEGER*4 access_name_buf 

END STRUCTURE !access_bit_names 

RECORD /access_bit_names/ my_names(32) 

access_mode 

BYTE 

address 

INTEGER»4 

address—range 

INTEGER»4(2) 

or 

STRUCTURE /address_range/ 

INTEGER*4 low_address 

INTEGER»4 high_address 

END STRUCTURE 

arg—list 

ast—procedure 

boolean 

INTEGER*4(n) 

EXTERNAL 

LOGICAL*4 

byte—signed 
byte—unsigned 

channel 

BYTE 

BYTE’ 

INTEGER->2 

char—string 

complex—number 

CHARACTER-n 

COMPLEX'S 

COMPLEX'16 

cond—value 

INTEGER'4 

context 

INTEGER'4 

date—time 

INTEGER'4(2) 

device—name 

CHARACTER'n 

ef—cluster—name 

CHARACTER'D 

ef—number 

INTEGER'4 


’Unsigned data types are not directly supported by VAX FORTRAN. However, in most 
cases you can substitute the signed equivalent as long as you do not exceed the range of 
the signed data structure. 
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Table A-8 (Cent.) VAX FORTRAN Implementation 


VMS Data Type VAX FORTRAN Declaration 


exit—handler—block 

STRUCTURE /exhblock/ 


INTEGER- 

4 flink 


INTEGER- 

4 exit—handler—addr 


BYTE(3) 

101 


BYTE arg 

—Count 


INTEGER- 

1 

4 cond—value 


1 .(optional arguments . . . 


! . one argument per longword) 

! 


END STRUCTURE Icntrlblk 


RECORD /exhblock/ myexh_block 

fab INCLUDE '{$FABDEF)' 

RECORD /fabdef/ myfab 

file—protection INTEGER*4 

floating-point REAL*4 

REAL*8 

DOUBLE PRECISION 
REAL* 16 


function—code 


INTEGER*4 


identifier INTEGER*4 

io—status—block STRUCTURE /iosb/ 

INTEGER*2 iostat, Ireturn status 
2 term—offset. Hoc. of line terminator 
2 terminator, lvalue of terminator 
2 term—size Isize of terminator 
END STRUCTURE 

RECORD /iosb/ my-iosb 

item—list—2 STRUCTURE /itmist/ 

UNION 

MAP 

INTEGER*2 buflen,code 
INTEGER*4 bufadr 
END MAP 
MAP 

INTEGER*4 end-list /O/ 

END MAP 
END UNION 

END STRUCTURE litmist 


RECORD /itmist/ my—itmist—2(n) 

(Allocate n records where n is the number 
of item codes plus an extra element for the 
end-of-list Item.) 
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Table A-8 (Cent.) 

VAX FORTRAN Implementation 

VMS Data Type 

VAX FORTRAN Declaration 

item_list_3 

STRUCTURE /itmist/ 

UNION 

MAP 

INTEGER*2 buflen,code 

INTEGER*4 bufadr,retlenadr 

END MAP 

MAP 

INTEGER*4 end-list /O/ 

END MAP 

END UNION 

END STRUCTURE litmist 

item_list_pair 

RECORD /itmist/ my—itmist—2(n) 

(Allocate n records where n is the number 
of item codes plus an extra element for the 
end-of-list item.) 

STRUCTURE /itmlist-pair/ 

UNION 

MAP 

INTEGER*4 code 

INTEGER*4 value 

END MAP 

MAP 

INTEGER*4 end—list /O/ 

END MAP 

END UNION 

END STRUCTURE litmist—pair 

item_quota_list 

RECORD /itmist—pair/ my—itmist—pair(n) 
(Allocate n records wfiere n is the number 
of item codes plus an extra element for the 
end-of-list item.) 

STRUCTURE /item—quota—list/ 

MAP 

BYTE quota—name 

INTEGER*4 quota-value 

END MAP 

MAP 

BYTE end—quota—list 

END MAP 

END STRUCTURE litem—quota—list 

lock_id 

INTEGER*4 

lock_status_block 

STRUCTURE/lksb/ 

INTEGER*2 cond—value 

INTEGER*2 unused 

INTEGER*4 lock-id 

BYTE(16) 

END STRUCTURE Mock—status—lock 

lock_value_block 

BYTE(16) 

logical-name 

CHARACTER^ 
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Table A-8 (Cent.) VAX FORTRAN Implementation 


VMS Data Type 

VAX FORTRAN Declaration 

longword—signed 

INTEGER*4 

longword—unsigned 

INTEGER*4’ 

mask—byte 

INTEGER* 1 

mask—longword 

INTEGER*4 

mask_quadword 

INTEGER*4(2) 

mask—word 

INTEGER*2 

null—arg 

%VAL{0) 

octaword—signed 

INTEGER*4(4) 

octaword—unsigned 

INTEGER*4{4)’ 

page—protection 

INTEGER*4 

procedure 

INTEGER*4 

process-id 

INTEGER*4 

process—name 

CHARACTER*n 

quadword—signed 

INTEGER*4(2) 

quadword—unsigned 

INTEGER*4(2)’ 

rights—holder 

INTEGER*4{2) 

or 

STRUCTURE /rights-holder/ 

INTEGER*4 rights—id 

INTEGER*4 rights—mask 

END STRUCTURE IrightS-holder 

rights—id 

INTEGER*4 

rab 

INCLUDE '(SRABDEF)' 

RECORD /rabdef/ myrab 

section—id 

INTEGER*4(2) 

section—name 

CHARACTER^ 

system —access—id 

INTEGER*4(2) 

time—name 

CHARACTER*23 

uic 

INTEGER*4 

user—arg 

Any longword quantity 

varying—arg 

INTEGER*4 

vector—byte—signed 

BYTE(n) 

vector—byte—unsigned 

BYTE(n)^ 

vector—longword—signed 

INTEGER*4(n) 

vector—longword—unsigned 

INTEGER*4(n)^ 

vector—quadword—signed 

INTEGER*4(2, n) 

vector—quadword—unsigned 

INTEGER*4(2,n)^ 


^Unsigned data types are not directly supported by VAX FORTRAN. However, in most 
cases you can substitute the signed equivalent as long as you do not exceed the range of 
the signed data structure. 
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Table A-8 (Cent.) 

VAX FORTRAN Implementation 

VMS Data Type 

VAX FORTRAN Declaration 

vector_word_signed 

INTEGER*2(n) 

vector_word_unsigned 

INTEGER*2{n)’ 

word—signed 

INTEGERo2{n) 

word—unsigned 

INTEGER‘2(n)’ 


’Unsigned data types are not directly supported by VAX FORTRAN. However, in most 
cases you can substitute the signed equivalent as long as you do not exceed the range of 
the signed data structure. 


VAX MACRO Implementation 

Table A-9 lists the VMS data types and their corresponding VAX MACRO 
data-type declarations. 

Table A-9 VAX MACRO Implementation 

VMS Data Type VAX MACRO Declaration 


access_bit—names 

.ASCID /name—for—bitO/ 

.ASCID /name—for—bit 1/ 


.ASCID /name—for—bit31 / 

access_mode 

.BYTE PSL$C-Xxxx 

address 

.ADDRESSS virtual—address 

address—range 

.ADDRESS start—address^end—address 

arg—list 

.LONG n—args, arg1, arg2, . . . 

ast—procedure 

.ADDRESS ast—procedure 

boolean 

.LONG 1 or .LONG 0 

byte—signed 

.SIGNED-BYTE byte-value 

byte—unsigned 

.BYTE byte—value 

channel 

.WORD channel—number 

char—string 

.ASCID /string/ 

complex—number 

NA 

cond—value 

.LONG cond—value 

context 

.LONG 0 

date—time 

.OUAD date—time 

device—name 

.ASCID /ddcu:/ 

ef—cluster—name 

.ASCID /ef—cluster—name/ 

ef—number 

.LONG ef—number 
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VAX MACRO Implementation 

VMS Data Type 

VAX MACRO Declaration 

exit_handler_block 

.LONG 0 

.ADDRESS exit—handler—routine 
.LONG 1 

.ADDRESS status 

STATUS: .BLKL 1 

fab 

MYFAB: $FAB 

file_protection 

.WORD prot—value 

floating-point 

.FLOAT, .G-FLOAT, or .H-FLOAT 

function—code 

.LONG codelmask 

identifier 

.ADDRESSS virtual—address 

io—status—block 

.QUAD 0 

item—list—2 

.WORD component—length 
.WORD item—code 
.ADDRESS component—address 

item-list—3 

.WORD buffer—length 
.WORD Item—code 
.ADDRESS buffer—address 
.ADDRESS return—length—address 

item—list—pair 

.LONG item—code 
.LONG data 

item—quota—list 

.BYTE PQL$-Xxxx 
.LONG value—for—quota 
.BYTE pql$—listend 

lock—id 

.LONG lock-id 

lock—status—block 

.QUAD 0 

lock—value—block 

.BLKB 16 

logical—name 

.ASCID /logical—name/ 

longword—signed 

.LONG value 

longword—unsigned 

.LONG value 

mask—byte 

.BYTE mask—byte 

mask—longword 

.LONG mask—longword 

mask—quadword 

.QUAD mask—quadword 

mask—word 

.WORD mask—word 

null—arg 

.LONG 0 

octaword—signed 

NA 

octaword—unsigned 

.OCTA value 

page—protection 

.LONG page—protection 

procedure 

.ADDRESS procedure 

process—id 

.LONG process—Id 

process—name 

.ASCID /process—name/ 

quadword—signed 

NA 
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Table A-9 (Cent.) VAX MACRO Implementation 

VMS Data Type 

VAX MACRO Declaration 

quadword—unsigned 

.QUAD value 

rights—holder 

.LONG identifier, access_rights_bitmask 

rights_id 

.LONG rights_id 

rab 

MYRAB: $RAB 

section _id 

.LONG sec$k_matXXX, version—number 

section _name 

.ASCID /section_name/ 

system _access_id 

.QUAD system—access—id 

time_name 

.ASCID /dd-mmm-yyyy:hh:mm:ss.cc/ 

uic 

.LONG uic 

user_arg 

.LONG data 

varying_arg 

Dependent upon application 

vector_byte_signed 

.SIGNED—BYTE vall,val2, . . . vaIN 

vector_byte_unsigned 

.BYTE vall,val2, . . . vaIN 

vector_longword_signed 

.LONG val1,val2, . . . vaIN 

vector_longword_unsigned 

.LONG val1,val2, . . . vaIN 

vector_quadword_signed 

NA 

veetor_quadvvord_unsigned 

.QUAD van 
.QUAD val2 


.QUAD vaIN 

vector_word_signed 

.SIGNED-WORD vall,val2, . . . vaIN 

vector_word_unsigned 

.WORD val1,val2, . . . vaIN 

word—signed 

.SIGNED-WORD value 

word—unsigned 

.WORD value 


A. 10 VAX PASCAL Implementation 

Table A-10 lists the VMS data types and their corresponding VAX PASCAL 
data-type declarations. 
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Table A—10 VAX PASCAL Implementation 


VMS Data Type 

VAX PASCAL Declaration 


access_bit_names 

PACKED ARRAY [1..32] OF [QUAD] RECORD END;’ ® 

access_mode 

[BYTE] 0..3;® 


address 

UNSIGNED; 


address_range 

PACKED ARRAY [1..2] OF UNSIGNED;® 


arg_list 

PACKED ARRAY [1..n] OF UNSIGNED;® 


ast_procedure 

UNSIGNED; 


boolean 

BOOLEAN;® 


byte_signed 

[BYTE] -128..127;® 


byte_unsigned 

[BYTE] 0..255;® 


channel 

[WORD] 0..65535;® 


char_string 

[CLASS_S] PACKED ARRAY [L..U:INTEGER] 

OF CHAR;'’ 

complex_number 

[LONG(2)] RECORD END; • F_Floating Complex o' ® 

[QUAD(2)] RECORD END; • D/G_Floating Complex • 

[OCTA(2)] RECORD END; • H-Floating Complex • 

cond—value 

UNSIGNED; 


context 

UNSIGNED; 


date_time 

[QUAD] RECORD END;’ ® 


device_name 

[CLASS_S] PACKED ARRAY [L..U:INTEGER] 

OF CHAR;'’ 

ef_cluster_name 

[CLASS_S] PACKED ARRAY [L..U:INTEGER] 

OF CHAR;'* 

ef_number 

UNSIGNED; 


exit_handler_block 

PACKED ARRAY [1..n] OF UNSIGNED;® 


fab 

FABSTYPE;® 


file—protection 

[WORD] RECORD END;’ ® 


floating-point 

REAL; 1 F_Floating ( 

SINGLE; | F_Floating ) 

DOUBLE; | D_Floating/G_Floating j® 
QUADRUPLE; j H_Floating ) 


function—code 

UNSIGNED; 


identifier 

UNSIGNED; 


io—status—block 

[QUAD] RECORD END;’ ® 


^This type is not available In 

VAX PASCAL when an empty record has been inserted. 

To manipulate the contents. 


declare with explicit field components. If you pass an empty record as a parameter to a PASCAL routine, you must use 
the VAR keyword. 

2If the [G_FLOATING] attribute is used in compiling, double-precision variables and expressions are represented in 
G_floating format. The /G_FLOATING command line qualifier can also be used. Both methods default to no G_floating. 

^VAX PASCAL allocates a byte for a BOOLEAN variable. Use the [LONG] attribute when passing to routines that expect 
a longword. 

^This parameter declaration accepts VARYING OF CHAR or PACKED ARRAY OF CHAR and produces the CLASS_S 
descriptor required by system services. 

®The program must Inherit the STARLET environment file located In SYS$LIBRARY:STARLET.PEN. 

®VAX PASCAL expects either a type identifier or conformant schema. Declare this under the TYPE declaration and use 
the type identifier in the formal parameter declaration. 
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Table A-10 (Cent.) 

VAX PASCAL Implementation 

VMS Data Type 

VAX PASCAL Declaration 

ltem_list_2 

PACKED ARRAY [1..n] OF PACKED RECORD® 

CASE INTEGER OF 

1: ( 

FIELD 1 : [WORD] 0..65535; 

FIELD2 : [WORD] 0..65535; 

FIELD3 : UNSIGNED); 

2: ( 

TERMINATOR : UNSIGNED); 

END; 

itenn_list_3 

PACKED ARRAY [1..n] OF PACKED RECORD® 

CASE INTEGER OF 

1: ( 

FIELD 1 : [WORD] 0..65535; 

FIELD2 : [WORD] 0 .65535; 

FIELD3 : UNSIGNED; 

FIELD4 : UNSIGNED); 

2: { 

TERMINATOR : UNSIGNED); 

END; 

item_list_pair 

PACKED ARRAY [1..n] OF PACKED RECORD® 

CASE INTEGER OF 

1: ( 

FIELD 1 : INTEGER; 

FIELD2 : INTEGER); 

2: ( 

TERMINATOR : UNSIGNED); 

END; 

itenn_quota_list 

PACKED ARRAY [1..n] OF PACKED RECORD® 

CASE INTEGER OF 

1: ( 

QUOTA_NAME : [BYTE] 0..255; 

QUOTA_VALUE; UNSIGNED); 

2: ( 

QUOTA-TERM : [BYTE] 0..255); 

END; 

lock_id 

UNSIGNED; 

lock_status_block 

[BYTE(24)] RECORD END;’ ® 

lock_value_block 

[BYTE(16)] RECORD END;’ ® 

logical-name 

longword—signed 

longword—unsigned 

[CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR;'’ 

INTEGER; 

UNSIGNED; 


^This type is not available In VAX PASCAL when an empty record has been inserted. To manipulate the contents, 
declare with explicit field components. If you pass an empty record as a parameter to a PASCAL routine, you must use 
the VAR keyword. 

^This parameter declaration accepts VARYING OF CHAR or PACKED ARRAY OF CHAR and produces the CLASS_S 
descriptor required by system services. 

®VAX PASCAL expects either a type Identifier or conformant schema. Declare this under the TYPE declaration and use 
the type identifier In the formal parameter declaration. 
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Table A-10 (Cont.) VAX PASCAL Implementation 


VMS Data Type 

VAX PASCAL Declaration 

mask_byte 

[BYTE.UNSAFE] PACKED ARRAY [1..8] OF BOOLEAN;® 

mask_longword 

[LONG.UNSAFE] PACKED ARRAY [1..32] OF BOOLEAN;® 

mask_quadword 

[QUAD.UNSAFE] PACKED ARRAY [1..64] OF BOOLEAN;® 

mask-_word 

[WORD.UNSAFE] PACKED ARRAY [1..16] OF BOOLEAN;® 

null_arg 

UNSIGNED; 

octaword—signed 

[OCTA] RECORD END;’ ® 

octaword—unsigned 

[OCTA] RECORD END;’ ® 

page—protection 

[LONG] 0..7;® 

procedure 

UNSIGNED; 

process_id 

UNSIGNED; 

process_name 

[CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR;'’ 

quadword—signed 

[QUAD] RECORD END;’ ® 

quadword—unsigned 

[QUAD] RECORD END;’ ® 

rights—holder 

[QUAD] RECORD END;’ ® 

rights_id 

UNSIGNED; 

rab 

RABSTYPE;® 

section _id 

[QUAD] RECORD END;’ ® 

section_name 

[CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR;'* 

system _access_ld 

[QUAD] RECORD END;’ ® 

time_name 

[CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR;'* 

uic 

UNSIGNED; 

user_arg 

[UNSAFE] UNSIGNED; 

varying_arg 

[UNSAFE.REFERENCE] PACKED ARRAY [L..U:INTEGER] OF [BYTE] 

0..255; 

vector_byte_signed 

PACKED ARRAY [1..n] OF [BYTE] -128.. 127;® 

vector_byte_unsigned 

PACKED ARRAY [1..n] OF [BYTE] 0..255;® 

vector_longword_signed 

PACKED ARRAY [1..n] OF INTEGER;® 

vector_longword_unsigned 

PACKED ARRAY [1..n] OF UNSIGNED;® 

vector_quadword_signed 

PACKED ARRAY [1..n] OF [QUAD] RECORD END;’ ® 

vector_quadword_unsigned 

PACKED ARRAY [1..n] OF [QUAD] RECORD END;’ ® 


^This type is not available in VAX PASCAL when an empty record has been inserted. To manipulate the contents, 
declare with explicit field components. If you pass an empty record as a parameter to a PASCAL routine, you must use 
the VAR keyword. 

"^This parameter declaration accepts VARYING OF CHAR or PACKED ARRAY OF CHAR and produces the CLASS_S 
descriptor required by system services. 

^The program must inherit the STARLET environment file located in SYS$LIBRARY:STARLET.PEN. 

®VAX PASCAL expects either a type Identifier or conformant schema. Declare this under the TYPE declaration and use 
the type Identifier in the formal parameter declaration. 
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Table A-10 (Cent.) 

VAX PASCAL Implementation 

VMS Data Type 

VAX PASCAL Declaration 

vector_word_signed 

vector_word_unslgned 

word_signed 

word—unsigned 

PACKED ARRAY [1..n] OF [WORD] -32768..32767;® 

PACKED ARRAY [1..n] OF [WORD] 0..65535;® 

[WORD] -32768..32767;® 

[WORD] 0 .65535;® 

®VAX PASCAL expects either a type identifier or conformant schema. Declare this under the TYPE declaration and use 
the type identifier In the formal parameter declaration. 


A. 11 VAX PL/I Implementation 

Table A-11 lists the VMS data types and their corresponding VAX PL/I 
data-type declarations. 


Table A-11 VAX PL/I Implementation 


VMS Data Type 

VAX PL/I Declaration 

access_bit_names 

1 ACCESS_BIT_NAMES{32), 

2 LENGTH FIXED BINARY] 15), 

2 DTYPE FIXED BINARY] 7) 
INITIAL]]32)DSC$K_DTYPE_T), 

2 CLASS FIXED BINARY] 7) 
INITIAL]]32)DSC$K_CLASS_S), 

2 CHAR_PTR POINTER;’ 


The length of the LENGTH field in each element 
of the array should correspond to the length of 
a string of characters pointed to by the 
CHAR_PTR field. The constants 
DST$K_CLASS_S and DST$K_DTYPE_T can 
be used by Including the module $DSCDEF from 
PLISTARLET or by declaring it GLOBALREF 
FIXED BINARY(31) VALUE. 

access_mode 

FIXED BINARY(7) 

(The constants for this type— 

PSL$C_KERNEL, PSL$C_EXEC, PSL$C_SUPER, 
PSL$C_USER—are declared in module $PSLDEF 
in PLISTARLET.)^ 

address 

POINTER 

address_range 

(2) POINTER^ 


^System routines are often written so the parameter passed occupies more storage than 
the object requires. For example, some system services have parameters that return a 
bit value as a longword. These variables must be declared BIT(32) ALIGNED (not BIT(n) 
ALIGNED) so adjacent storage is not overwritten by return values or used Incorrectly as 
input. (Longword parameters are always declared BIT(32) ALIGNED.) 

2 AST procedures and those passed as parameters of type ENTRY VALUE or ANY VALUE 
must be external procedures. This applies to all system routines that take procedure 
parameters. 
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Table A—11 (Cent.) 

VAX PL/I Implementation 

VMS Data Type 

VAX PL/I Declaration 

arg_list 

1 ARG_LIST BASED, 

2 ARGCOUNT FIXED BINARY(31), 

2 ARGUMENT (X REFER (ARGCOUNT)) 
POINTER;’ 

If the arguments are passed by value, you may 
need to change the type of the ARGUMENT 
field of the structure. Alternatively, you can use 
the POSINT, INT, or UNSPEC built-in functions 
/pseudovariables to access the data. X should 
be an expression with a value in the range 0 to 
255 when the structure is allocated. 

ast_procedure 

PROCEDURE or ENTRY^ 

boolean 

BIT ALIGNED^ 

byte_signed 

FIXED BINARY(7) 

byte_unsigned 

FIXED BINARY! 7)'’ 

channel 

FIXED BINARY! 15) 

char_string 

CHARACTER! n)® 

complex_number 

(2) FLOAT BINARY!n) (See floating-point for 
values of n.) 

cond—value 

See module STS$VALUE in PLISTARLET.’ 

context 

FIXED BINARY!31) 

date_time 

BIT!64) ALIGNED® 

device_name 

CHARACTER! n)® 

ef_cluster_name 

CHARACTER! n)® 


^System routines are often written so the parameter passed occupies more storage than 
the object requires. For example, some system services have parameters that return a 
bit value as a longwofd. These variables, must be declared BIT(32) ALIGNED (not BIT(n) 
ALIGNED) so adjacent storage is not overwritten by return values or used incorrectly as 
input. (Longword parameters are always declared BIT(32) ALIGNED.) 

^AST procedures and those passed as parameters of type ENTRY VALUE or ANY VALUE 
must be external procedures. This applies to all system routines that take procedure 
parameters. 

^This is actually an unsigned integer. This declaration is interpreted as a signed number; 
use the POSINT function to determine the actual value. 

^System services require CHARACTER string representation for parameters. Most other 
system routines allow either CHARACTER or CHARACTER VARYING. For parameter 
declarations, n should be an asterisk (•). 

®VAX PL/I does not support FIXED BINARY numbers with precisions greater than 32. 

To use larger values, declare variables to be BIT variables of the appropriate size and use 
the POSINT and SUBSTR bits as necessary to access the values, or declare the Item as 
a structure. The RTL routines LIB$ADDX and LIB$SUBX may be useful If you need to 
perform arithmetic on these types. 

®Routines declared In PLISTARLET often use ANY so you are free to declare the data 
structure in the most convenient way for the application. ANY may be necessary In some 
cases because PL/I does not allow parameter declarations for some data types used by 
VMS. (In particular, PL/I parameters with arrays passed by reference cannot be declared to^ 
have nonconstant bounds.) 
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Table A-11 (Cent.) VAX PL/I Implementation 


VMS Data Type 

VAX PL/I Declaration 

ef_number 

FIXED BINARY{31) 

exit_handler_block 

1 EXIT_HANDLER_BLOCK BASED, 

2 FORWARD_LINK POINTER, 

2 HANDLER POINTER, 

2 ARGCOUNT FIXED BINARY(31), 

2 ARGUMENT (n REFER 
(ARGCOUNT) POINTER;’ 

fab 

Replace n with an expression that yields a 
value between 0 and 255 when the structure is 
allocated. 

See module $FABDEF in PLISTARLET.^ 

file—protection 

floating-point 

BIT(16) ALIGNED^ 

FLOAT BINARY(n) 

The values for n are as follows: 

1 <= n <= 24 - F floating 

25 <= n <= 53 - D floating 

25 <= n <= 53 - G floating (with /G—FLOAT) 
54 <= n <= 113 - H floating 

function—Code 

BIT(32) ALIGNED 

identifier 

POINTER 


^System routines are often written so the parameter passed occupies more storage than 
the object requires. For example, some system services have parameters that return a 
bit value as a longword. These variables must be declared BIT(32) ALIGNED (not BIT(n) 
ALIGNED) so adjacent storage is not overwritten by return values or used Incorrectly as 
input. (Longword parameters are always declared BIT(32) ALIGNED.) 

2 AST procedures and those passed as parameters of type ENTRY VALUE or ANY VALUE 
must be external procedures. This applies to ail system routines that take procedure 
parameters. 
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VMS Data Type VAX PL/I Declaration 

io_status_block Because there are different formats for I/O 

status blocks for various system services, 
different definitions are appropriate for different 
uses. Some of the common formats are as 
follows; 


/• See the VMS System Services Reference 
Manual. */ 

1 IOSB_SYS$GETSYI, 

2 STATUS FIXED BINARY(31), 

2 RESERVED FIXED BINARY(31); 

/• See the VMS I/O User's Reference Manual: 
Part /. •/ 

1 IOSB_TTDRIVER_A, 

2 STATUS FIXED BINARY(15), 

2 BYTE-COUNT FIXED BINARY! 15), 

2 MBZ FIXED BINARY(31) INITIAL!0); 

/* See the VMS I/O User's Reference Manual: 
Part I. •/ 

1 IOSB_TTDRIVER_B, 

2 STATUS FIXED BINARY! 15), 

2 TRANSMIT-SPEED FIXED 
BINARY!?), 

2 RECEIVE-SPEED FIXED BINARY!?), 
2 CR_FILL FIXED BINARY!?), 

2 LF_FILL FIXED BINARY!?), 

2 PARITY-FLAGS FIXED BINARY!?), 
2 MBZ FIXED BINARY!?) INITIAL!0); 

item-list-2 1 ITEM-LIST-2, 

2 ITEM!SIZE), 

3 COMPONENT-LENGTH FIXED 
BINARY!15), 

3 ITEM-CODE FIXED BINARY! 15), 
3 COMPONENT-ADDRESS 
POINTER, 

2 TERMINATOR FIXED BINARY!31) 
INITIAL! 0);’ 


Replace SIZE with the number of items you 
want. 


'System routines are often written so the parameter passed occupies more storage than 
the object requires. For example, some system services have parameters that return a 
bit value as a longword. These variables must be declared BIT!32) ALIGNED !not BIT!n) 
ALIGNED) so adjacent storage is not overwritten by return values or used incorrectly as 
input. ILongword parameters are always declared BIT!32) ALIGNED.) 
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Table A-11 (Cent.) VAX PL/I Implementation 


VMS Data Type 

VAX PL/I Declaration 

item_list_3 

1 ITEM_LIST_3, 

2 ITEM(SIZE), 

3 BUFFER-LENGTH FIXED 

BINARY! 15), 

3 ITEM_CODE FIXED BINARY! 15), 

3 BUFFER_ADDRESS POINTER, 

3 RETURN-LENGTH POINTER, 

2 TERMINATOR FIXED BINARYpI) 
INITIAL!0);’ 


Replace SIZE with the number of items you 
want. 

ltem_list_pair 

1 ITEM_LIST_PAIR, 

2 ITEM!SIZE), 

3 ITEM-CODE FIXED BINARY!31), 

3 ITEM UNION, 

4 INTEGER FIXED BINARY!31), 

0 REAL FLOAT BINARY!24), 

2 TERMINATOR FIXED BINARY!31) 
INITIAL! 0);’ 


Replace SIZE with the number of items you 
want. 

item_quota_list 

1 ITEM-QUOTA-LIST, 

2 QUOTA!SIZE), 

3 NAME FIXED BINARY!?), 

3 VALUE FIXED BINARY!31), 

2 TERMINATOR FIXED BINARY!?) 
INITIAL!PQL$-LISTEND);’ 


Replace SIZE with the number of quota entries 
you want to use. The constant PQL$_LISTEND 
can be used by including the module $PQLDEF 
from PLISTARLET or by declaring it GLOBALREF 
FIXED BINARY{31) VALUE. 

lock_id 

FIXED BINARY(31) 

lock_status_block 

1 LOCK_STATUS_BLOCK, 

2 STATUS-CODE FIXED BINARY(15), 

2 RESERVED FIXED BINARY(15), 

2 LOCK-ID FIXED BINARY(31);^ 

lock_value_block 

The declaration of an item of this structure 
depends on the use of the structure, because 
VMS does not interpret the value.^ 


^System routines are often written so the parameter passed occupies more storage than 
the object requires. For example, some system services have parameters that return a 
bit value as a longword. These variables must be declared BIT(32) ALIGNED (not BIT(n) 
ALIGNED) so adjacent storage is not overwritten by return values or used Incorrectly as 
Input. (Longword parameters are always declared BIT(32) ALIGNED.) 
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VAX PL/I Implementation 

VMS Data Type 

VAX PL/I Declaration 

logical_name 

CHARACTER! n)® 

longword—signed 

FIXED BINARY(31) 

longword—unsigned 

FIXED BINARYOD* 

mask_byte 

BIT(8) ALIGNED 

mask_longword 

BIT(32) ALIGNED 

mask_quadword 

BIT(64) ALIGNED 

mask_word 

BIT(16) ALIGNED 

null_arg 

Omit the corresponding parameter in the call. 

For example, FOO(A„B) would omit the second 
parameter. 

octaword—signed 

BIT{128) ALIGNED® 

octaword—unsigned 

BIT(128) ALIGNED'* ® 

page_protection 

FIXED BINARY(31) (The constants for this 
type are declared in module $PRTDEF in 
PLISTARLET.) 

procedure 

PROCEDURE or ENTRY® 

process_id 

FIXED BINARY(31) 

process_name 

CHARACTER! n)® 

quadword—signed 

BIT!64) ALIGNED® 

quadword—unsigned 

BIT!64) ALIGNED'* ® 

rights—holder 

1 RIGHTS-HOLDER, 

2 RIGHTS_ID FIXED BINARYPI), 

2 ACCESS-RIGHTS BIT!32) 

ALIGNED;’ 

rights_ld 

FIXED BINARY!31) 

rab 

See module SRABDEF in PLISTARLET’ 


^System routines are often written so the parameter passed occupies more storage than 
the object requires. For example, some system services have parameters that return a 
bit value as a longword. These variables must be declared BIT(32) ALIGNED (not BIT(n) 
ALIGNED) so adjacent storage Is not overwritten by return values or used incorrectly as 
Input. (Longword parameters are always declared BIT(32) ALIGNED.) 

^Thls is actually an unsigned integer. This declaration is interpreted as a signed number; 
use the POSINT function to determine the actual value. 

^System services require CHARACTER string representation for parameters. Most other 
system routines allow either CHARACTER or CHARACTER VARYING. For parameter 
declarations, n should be an asterisk (*). 

®VAX PL/I does not support FIXED BINARY numbers with precisions greater than 32. 

To use larger values, declare variables to be BIT variables of the appropriate size and use 
the POSINT and SUBSTR bits as necessary to access the values, or declare the item as 
a structure. The RTL routines LIB$ADDX and LIB$SUBX may be useful if you need to 
perform arithmetic on these types. 

^Routines declared in PLISTARLET often use ANY so you are free to declare the data 
structure in the most convenient way for the application. ANY may be necessary in some 
cases because PL/I does not allow parameter declarations for some data types used by 
VMS. (In particular, PL/I parameters with arrays passed by reference cannot be declared to 
have nonconstant bounds.) 
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Table A-11 (Cent.) VAX PL/I Implementation 


VMS Data Type 

VAX PL/I Declaration 

section _id 

BIT(64) ALIGNED 

section_name 

CHARACTER(n)® 

system _access_id 

BIT(64) ALIGNED 

tlme_name 

CHARACTER! n)® 

uic 

FIXED BINARY(31) 

user_arg 

ANY 

varying_arg 

ANY with OPTIONSiVARIABLE) on the routine 
declaration 

vector_byte_signed 

(n) FIXED BINARY!7)’ 

vector_byte_unsigned 

!n) FIXED BINARY!7 

vector_longword_signed 

!n) FIXED BINARYISI)^ 

vector_longword_unsigned 

!n) FIXED BINARYPI)'*’^ 

vector_quadword_signed 

!n) BIT!64) ALIGNED®'^ 

vector_quadword_unsigned 

!n) BIT!64) ALIGNED'*’®’^ 

vector_word_signed 

!n) FIXED BINARYIIB)^ 

vector_word_unsigned 

!n) FIXED BINARY! 15)'*’^ 

word—signed 

FIXED BINARY! 15) 

word—unsigned 

FIXED BINARY! 15)'* 


^System services require CHARACTER string representation for parameters. Most other 
system routines allow either CHARACTER or CHARACTER VARYING. For parameter 
declarations, n should be an asterisk (*). 

^VAX PL/I does not support FIXED BINARY numbers with precisions greater than 32. 

To use larger values, declare variables to be BIT variables of the appropriate size and use 
the POSINT and SUBSTR bits as necessary to access the values, or declare the item as 
a structure. The RTL routines LIB$ADDX and LIB$SUBX may be useful if you need to 
perform arithmetic on these types. 

^Routines declared in PLISTARLET often use ANY so you are free to declare the data 
structure in the most convenient way for the application. ANY may be necessary in some 
cases because PL/I does not allow parameter declarations for some data types used by 
VMS. (In particular, PL/I parameters with arrays passed by reference cannot be declared to 
have nonconstant bounds.) 

^For parameter declarations, the bounds must be constant for arrays passed by reference. 
For arrays passed by descriptor, *s should be used for the array extent Instead. (VMS 
system routines almost always take arrays by reference.) 


Note: All system services and many system constants and data structures 

are declared in PLISTARLET.TLB. For examples of how to use system 
services, see either the VAX-11 PL/I User's Guide or Programming in 
VAX-11 PL/I. 

Important note: While the current version of VAX PL/I Version 3 does 
not support unsigned fixed binary numbers or fixed binary numbers 
with a precision greater that 31, future versions may support these 
features. If VAX PL/I is extended to support these types, declarations in 
PLISTARLET may change to use the new data types where appropriate. 
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A.12 VAX RPG II Implementation 


Table A-12 lists the VMS data types and their corresponding VAX RPG II 
data-type declarations. 

Table A-12 VAX RPG II Implementation 


VMS Data Type 

VAX RPG II Declaration 

access_bit_names 

NA 

access_mode 

Declare as text string of one byte. When 
using this data structure, you must 
interpret the ASCII contents of the string to 
determine the access—mode. 

address 


address_range 

Q' 

arg_list 

NA 

ast_procedure 


boolean 

NA 

byte_signed 

Declare as text string of one byte. When 
using this data structure, you must interpret 
the ASCII contents of the string. 

byte_unsigned 

Same as for byte—signed.^ 

channel 

W^ 

char_string 

TEXT STRING 

complex_number 

DATA STRUCTURE 

cond_value 

cond—value GIVNG OPCODE 

context 

L’ 

date_time 

0^ 

device_name 

TEXT STRING 

ef_cluster_name 

TEXT STRING 

ef_number 

L' 

exlt_handler_block 

DATA STRUCTURE 

fab 

Implicitly generated by the compiler on your 
behalf. You cannot access the fab data 
structure from an RPG II program. 

file_protection 

W^ 

floating-point 

F 

D 

function_code 

F 

identifier 

L' 

io—status—block 

0 

item—list—pair 

DATA STRUCTURE 


^Technically, RPG II does not support unsigned data structures. However, unsigned 
information may be passed using the signed equivalent, provided the contents do not 
exceed the range of the signed data structure. 
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Table A-12 (Cent.) 

VAX RPG II Implementation 

VMS Data Type 

VAX RPG II Declaration 

item_list_2 

DATA STRUCTURE 

item_list_3 

DATA STRUCTURE 

item_quota_list 

NA 

lock_id 

L’ 

lock_status_block 

DATA STRUCTURE 

lock_value_block 

DATA STRUCTURE 

logical-name 

TEXT STRING 

longword—signed 

L 

longword—unsigned 

L’ 

mask-byte 

Same as for byte_signed^ 

mask—longword 

L’ 

mask—quadword 

Q’ 

mask—word 

W’ 

null—arg 

NA 

octaword—signed 

DATA STRUCTURE 

octaword—unsigned 

DATA STRUCTURE 

page—protection 

L’ 

procedure 

L’ 

process—id 

L’ 

process—name 

TEXT STRING 

quadword—signed 

Q 

quadword—unsigned 

Q’ 

rights—holder 

Q’ 

rights—id 

L’ 

rab 

Implicitly generated by the compiler on your 
behalf. You cannot access the rab data 
structure from an RPG II program. 

section—id 

q’ 

section—name 

TEXT STRING 

system —access—id 

Q’ 

time—name 

TEXT STRING 

uic 

L’ 

user—arg 

L' 

varying—arg 

Dependent upon application 

vector—byte—signed 

ARRAY OF TEXT STRING 

vector—byte—unsigned 

ARRAY OF TEXT STRING’ 


^Technically, RPG II does not support unsigned data structures. However, unsigned 
information may be passed using the signed equivalent, provided the contents do not 
exceed the range of the signed data structure. 
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A.13 


Table A—12 (Cont.) VAX RPG II Implementation 

VMS Data Type VAX RPG II Declaration 


vector_longword_signed 

ARRAY OF LONGWORD INTEGER (SIGNED) 
L 

vector_longword_unsigned 

RAY OF LONGWORD INTEGER L’ 

vector_quadword_signed 

NA 


vector_quadword_unsigned 

NA 


vector_word_signed 

ARRAY OF WORD INTEGER (SIGNED) W 

vector_word_unsigned 

ARRAY OF WORD INTEGER W’ 

word_signed 

W 


word—unsigned 

W’ 


^Technically, RPG II does not support unsigned data structures. However, unsigned 
information may be passed using the signed equivalent, provided the contents do not 
exceed the range of the signed data structure. 



VAX SCAN Implementation 



Table A-13 lists the VMS data types and their corresponding VAX SCAN 
data-type declarations. 

Table A—13 VAX SCAN Implementation 


VMS Data Type 

VAX SCAN Declaration 

access_bit_name 

FILL( 8*32 )’ 


access_mode 

FILL( 1 


address 

POINTER 


address_range 

RECORD 

start: POINTER, 
end: POINTER, 
END RECORD 


arg_list 

RECORD 

count: INTEGER 
argl: POINTER, 
arg2: INTEGER, 
... I dependinc 
END RECORD 

[, 

I if by reference 

1 if by value 

1 on needs 

ast_procedure 

POINTER 


boolean 

BOOLEAN^ 


byte_signed 

FILM 1 )’ 


byte_unsigned 

FILM 1 )’ 


^FILL is a data type that can always be used. A FILL is an object between 0 and 65K 
bytes in length. VAX SCAN does not interpret the contents of an object. Thus, It can be 
used to pass or return the object to another language that does understand the type. 

^SCAN Boolean is just one byte. 
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Table A-13 (Cont.) 

VAX SCAN Implementation 

VMS Data Type 

VAX SCAN Declaration 

channel 

FILL! 2 

char_string 

complex_nunnber 

cond_value 

FIXED STRING! x ) where x is length 

FILL! X ) where x is length’ 

INTEGER 

context 

INTEGER 

date_time 

FILL! 8 )’ 

device_name 

FIXED STRING! x ) where x is length 

ef_cluster_name 

FIXED STRING! x ) where x is length 

ef_number 

INTEGER 

exit_handler_block 

FILL! X ) where x is length’ 

fab 

A fab is too complicated a structure to include 
in this chart—much of it can be described with a 
SCAN record; however, it is much simpler and less 
prone to error to access fabs from other languages 
that have the record predefined. 

file_protection 

floating-point 

function—code 

FILL! 2 )’ 

FILL! X ) where x is length’ 

INTEGER 

identifier 

POINTER 

io—status—block 

item_llst—2 

FILM 8 )’ 

RECORD 

itemi: FILL! 8 ), 
item2: FILL! 8 ), 

item—list—3 

terminator: INTEGER, 

END RECORD’ 

RECORD 

itemi; FILL! 12 ), 
item2: FILL! 12 ), 

terminator: INTEGER, 

END RECORD’ 


^FILL is a data type that can always be used. A FILL is an object between 0 and 65K 
bytes in length. VAX SCAN does not interpret the contents of an object. Thus, it can be 
used to pass or return the object to another language that does understand the type. 
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Table A-13 (Cont.) 

VAX SCAN Implementation 

VMS Data Type 

VAX SCAN Declaration 

item_list_pair 

RECORD 

pair_1: RECORD ! 2 integer pair 
longl: INTEGER, 
long2: INTEGER, 

END RECORD, 

pair_2: RECORD 1 integer-real pair 
longl: INTEGER, 
long2: FILL(4), 

END RECORD, 

1 depending on need 
terminator: INTEGER, 

END RECORD 

item_quota_list 

RECORD 

itemi: RECORD 

type: FILL( 1 ), 
value: INTEGER, 

END RECORD, 
item2: RECORD 

type: FILL( 1 ), 
value: INTEGER, 

END RECORD, 

terminator: FILL( 1 ), 

END RECORD’ 

lock_id 

INTEGER 

lock_status_block 

RECORD 

status: FILM 2 ), 
reserved: FILM 2 ), 
lock_id: INTEGER, 

END RECORD’ 

lock_value_block 

FILM 16 )’ 

logical-name 

FIXED STRING! x ) where x is length 

longword—signed 

INTEGER 

longword—unsigned 

INTEGER 

mask—byte 

FILM 1 )’ 

mask—longword 

INTEGER 

mask—quadword 

RECORD 

first-half: INTEGER, 
second-half: INTEGER, 

END RECORD 

mask—word 

FILM 2 )’ 

null—arg 

Use asterisk (•) for argument. 

octaword—signed 

FILM 16 )’ 

octaword—unsigned 

FILL! 16 )’ 


^FILL is a data type that can always be used. A FILL is an object between 0 and 65K 
bytes in length. VAX SCAN does not interpret the contents of an object. Thus, it can be 
used to pass or return the object to another language that does understand the type. 
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Table A-13 (Cent.) VAX SCAN Implementation 


VMS Data Type 

VAX SCAN Declaration 

page_protectlon 

INTEGER 

procedure 

POINTER 

process_id 

INTEGER 

process_name 

FIXED STRING! x ) where x is length 

quadword—signed 

FILM 8 )’ 

quadword-unsigned 

FILM 8 )’ 

rights—holder 

RECORD 

rights—id: INTEGER, 
bitmask: INTEGER, 



END RECORD 

rights_id 

INTEGER 

rab 

A rab is too complicated a structure to Include 
in this chart—much of It can be described with a 
SCAN record; however, it is much simpler and less 
prone to error to access rabs from other languages 
that have the record predefined. 

second_name 

FILL( 8 

section—name 

FIXED STRING! x ) where x is length 

system _access_id 

FILL! 8 

time_name 

FIXED STRING! x ) where x is length 

uic 

INTEGER 

user_arg 

INTEGER 

varying_arg 

INTEGER 

vector—byte_signed 

FILL! X ) where x is length^ 

vector—byte—unsigned 

FILL! X ) where x is length^ 

vector—longword—signed 

FILL! 4*x ) where x is length^ 

vector—longword—unsigned 

FILL! 4*x ) where x is length^ 

vector—quadword—signed 

FILL! 8*x ) where x is length^ 

vector—quadword—unsigned 

FILL! 8*x ) where x is length^ 

vector—word—signed 

FILL! 2*x ) where x Is length^ 

vector—word—unsigned 

FILL! 2*x ) where x is length^ 

word—signed 

FILL! 2 

word—unsigned 

FILL! 2 y 

^FILL is a data type that can always be used. A FILL is an object between 0 and 65K 
bytes in length. VAX SCAN does not Interpret the contents of an object. Thus, it can be 
used to pass or return the object to another language that does understand the type. 
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A 


Access entry 

See Routine format 
Access method 
See Routine format 
Ada implementation table 
See Implementation table 
Address 

definition of •2-3 
APL implementation table 
See Implementation table 
Argument data type 
See Data type 
Argument list 

definition of •2-3 
Arguments heading 
See Routine format 
Array descriptor 
See Descriptor 
Atomic data type 
See Data type 


B 


BASIC implementation table 
See Implementation table 
BLISS implementation table 
See Implementation table 


c 


Calling sequence • 2-4 
Calling standard 

See VAX Procedure Calling Standard 
C implementation table 
See Implementation table 
COBOL implementation table 
See Implementation table 


COBOL intermediate temporary data type 
See Data type 
Condition 

See Exception condition 
Condition handler • 2-42 
deleting • 2-44 
establishing • 2-44 
memory 

use of • 2-48 

multiple active signals •2-51 
operations involving • 2-43 
options • 2-43 

parameters and invocation • 2-46 
properties of •2-46 
register values •2-50 
request to unwind • 2-49 
returning from • 2-48 
stack usage • 2-43 
Condition Handling Standard 

See VAX Condition Handling Standard 
Condition value 

See also Routine format 
definition of • 2-3 
description of^*2-8 
field 

cntrl • 2-9 

condition Identification • 2-8 
facility • 2-8 
message number • 2-8 
severity code • 2-8 
registers 

use of • 2-11 
returned 

I/O status blocks 1-14 
mailbox • 1-14 
RO^l-14 
severity code 

interpretation of •2-10 
signaled • 1-15 
symbols for • 2-9 
use of • 2-11 


D 


Data type •2-13 
atomic • 2-13 
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Data type 

atomic (cont'd.) 

DSC$K_DTYPE_B *2-14 
DSC$K_DTYPE _BU *2-13 
DSC$K_DTYPE_CIT •2-15 
DSC$K_DTYPE _D • 2-14 
DSC$K_DTYPE_DC *2-14 
DSC$K_DTY_F«2-14 
DSC$K_DTYPE_FC •2-14 
DSC$K_DTYPE _G • 2-14 
DSC$K_DTYPE_GC • 2-14 
DSC$K_DTYPE_H • 2-14 
DSC$K_DTYPE_HC • 2-15 
DSC$K_DTYPE_L • 2-14 
DSC$K_DTYPE_LU • 2-13 
DSC$K_DTYPE_0• 2-14 
DSC$K_DTYPE_OU•2-14 
DSC$K_DTYPE_Q • 2-14 
DSC$K_DTYPE_QU • 2-13 
DSC$K_DTYPE_W • 2-14 
DSC$K_DTYPE_WU • 2-13 
DSC$K_DTYPE _Z • 2-13 
COBOL intermediate temporary •2-18 
code 

facility-specific • 2-17 
reserved •2-18 
miscellaneous •2-16 

DSC$K_DTYPE_ADT • 2-17 
DSC$K_DTYPE_BLV • 2-17 
DSC$K_DTYPE_BPV • 2-16 
DSC$K_DTYPE_DSC • 2-16 
DSC$K_DTYPE_ZEM • 2-16 
DSC$K_DTYPE_ZI • 2-16 
strings 2-15 

DSC$K_DTYPE_NL^2-15 
DSC$K_DTYPE_NLO • 2-16 
DSC$K_DTYPE _NR • 2-16 
DSC$K_DTYPE_NRO • 2-16 
DSC$K_DTYPE_NU • 2-15 
DSC$K_DTYPE_NZ •2-16 
DSC$K_DTYPE_P • 2-16 
DSC$K_DTYPE_T • 2-15 
DSC$K_DTYPE_V • 2-16 
DSC$K_DTYPE_VT^2-15, 2-19 
DSC$K_DTYPE_VU•2-16 
varying character string •2-19 
DSC$K_DTYPE_VT•2-19 
VAX standard • 1-8 
VMS 

definition of^ A-1 
description of •A-1 to A-18 


Data type (cont’d.) 

VMS Usages 1-8 
Decimal string descriptor 
See Descriptor 
Descriptor 
arrays 2-22 
class codes 

facility-specific • 2-41 
reserved • 2-41 
decimal string • 2-26 
dynamic string • 2-22 
fixed-length • 2-21 
format • 2-19 

DSC$ A_POINTER • 2-21 
DSC$B_CLASS^2-21 
DSC$B_DTYPE^2-20 
DSC$K_CLASS_A • 2-22 
DSC$K_CLASS_D • 2-22 
DSC$K_CLASS_J•2-26 
DSC$K_CLASS_NCA • 2-28 
DSC$K_CLASS_P•2-26 
DSC$K_CLASS_S•2-21 
DSC$K_CLASS_SB•2-38 
DSC$K_CLASS_SD•2-26 
DSC$K_CLASS_UBA • 2-35 
DSC$K_CLASS_UBS•2-34 
DSC$K_CLASS_UBSB•2-39 
DSC$K_CLASS_V • 2-22 
DSC$K_CLASS_VS•2-30 
DSC$K_CLASS_VSA • 2-32 
DSC$W_LENGTH • 2-20 
prototype • 2-20 
labels 2-26 

noncontiguous array • 2-28 
procedure • 2-26 
string with bounds • 2-38 
unaligned bit array •2-35 
unaligned bit string • 2-34 
unaligned bit string with bounds • 2-39 
variable buffer • 2-22 
varying string • 2-30 
varying string array • 2-32 
Dynamic string descriptor 
See Descriptor 


E 


Exception condition • 2-3 
definition of •2-41 
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Exception condition (cont'd.) 
indicating occurrence of *2-44 
signaling an • 2-44 


Implementation table (cont'd.) 
VAX SCAN»A-55 
VMS Usage* A-1 


F 


L 


Facility-specific data type code 
See Data type 

Facility-specific descriptor class codes 
See Descriptor 
Fixed-length descriptor 
See Descriptor 
Format heading 
See Routine format 
FORTRAN implementation table 
See Implementation table 
Function 

definition of •2-3 
Function value *2-7 
registers 

use of*2-11 


H 


High-level language 

argument evaluation • 2-6 
argument transmission • 2-6 
mapped into argument lists *2-5 



I 


Immediate value 


See Passing mechanism 
Implementation table 


VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 

VAX 


Ada*A-18 
APL*A-20 
BASIC •A-23 
BLISS •A-26 
C*A-29 
COBOL •A-32 
FORTRAN •A-SB 
MACRO •A-AO 
PASCAL •A-42 
PL/l*A-46 
RPG II^A-BS 


Label descriptor 
See Descriptor 
Language extension 

See VAX language extension 
Language support procedure 
See Procedure 
Library procedure 
See Procedure 


M 


MACRO implementation table 
See Implementation table 
Mechanism entry 
See Routine format 
Miscellaneous data type 
See Data type 
Multiple active signal 
See Condition handler 



Noncontiguous array descriptor 
See Descriptor 


o 


Operation involving condition handler 
See Condition handler 


p 


PASCAL implementation table 
See Implementation table 
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Passing mechanism 

See also Routine format 
descriptor 

definition of •2-3 
reference 

definition of *2-3 
value 

definition of *2-3 
PL/I implementation table 
See Implementation table 
Procedure 

definition of *2-3 
language support 
definition of *2-3 
use of *2-3 
library 

definition of *2-3 
use of *2-3 
Procedure descriptor 
See Descriptor 

Properties of condition handler 
See Condition handler 


R 


Register 

See Condition value 
See Function value 
Request to unwind 
See Condition handler 
Reserved data type code 
See Data type 

Reserved descriptor class code 
See Descriptor 

Returning from condition handler 
See Condition handler 
Returns heading 
See Routine format 
Revert to the caller's handling 
See Condition handler 
Routine format 

arguments heading* 1-7 
access entry* 1-10 
mechanism entry* 1-11 
text entry* 1-12 
type entry *1-8 
VMS Usage entry* 1-8 


Routine format (cont'd.) 

condition values returned heading* 
1-13 to 1-15 
description of * 1-1 
format heading* 1-3 
returns heading* 1-5 

condition values* 1-6 to 1-7 
data * 1 -6 

RPG II Implementation table 
See Implementation table 


s 


SCAN implementation table 
See Implementation table 
Severity code 

See Condition value 
Signaler's register 

^ee Condition handler 
Signaling a condition 
See Condition handler 
Stack usage *2-12 

See also Condition handler 
String data type 
See Data type 

String with bounds descriptor 
See Descriptor 
Subroutine 

definition of *2-3 
System routine template 
See Routine format 


T 


Text entry 

See Routine format 
Type entry 

See Routine format 


u 


Unaligned bit array descriptor 
See Descriptor 
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Unaligned bit string descriptor 
See Descriptor 

Unaligned bit string with bounds descriptor 
See Descriptor 
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